ScyllaDB University LIVE, FREE Virtual Training Event | March 21
Register for Free
ScyllaDB Documentation Logo Documentation
  • Server
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
  • Resources
    • ScyllaDB University
    • Community Forum
    • Tutorials
Download
ScyllaDB Docs ScyllaDB Enterprise ScyllaDB for Administrators System Configuration Configure ScyllaDB

Caution

You're viewing documentation for a previous version. Switch to the latest stable version.

Configure ScyllaDB¶

System configuration steps are performed automatically by the ScyllaDB RPM and deb packages. For information on getting started with ScyllaDB, see Getting Started.

All ScyllaDB AMIs and Docker images are pre-configured by a script with the following steps. This document is provided as a reference.

System Configuration Files and Scripts¶

Several system configuration settings should be applied. For ease of use, the necessary scripts and configuration files are provided. Files are under dist/common and seastar/scripts in the ScyllaDB source code and installed in the appropriate system locations. (For information on ScyllaDB’s own configuration file, see ScyllaDB Configuration.)

System Configuration Files¶

File Name

Description

scylla.conf

Remove system resource limits

scylla-server

Server startup options

(written by scylla_coredump_setup, below)

Configure core dumps to use the scylla_save_coredump script

ScyllaDB Scripts¶

The following scripts are available for you to run for configuring ScyllaDB. Some of these scripts are included in the scylla_setup script. This script is used for configuring ScyllaDB the first time, or when the system hardware changes.

ScyllaDB Setup Scripts¶

perftune.py

Configures various system parameters in order to improve the Seastar application performance

scylla_bootparam_setup

Sets the kernel options in the bootloader. In addition, it tunes Linux boot-time parameters for the node that ScyllaDB is running on (e.g. huge page setup).

scylla_coredump_setup

Sets up coredump facilities for ScyllaDB. This may include uninstalling existing crash reporting software for compatibility reasons.

scylla_io_setup

Benchmarks the disks and generates the io.conf and io_properties.yaml files.

scylla_ntp_setup

Configures Network Time Protocol

scylla_prepare

This script is run automatically every time ScyllaDB starts and the machine needs to be tuned.

scylla_raid_setup

Configures RAID and makes an XFS filesystem.

scylla_save_coredump

Compresses a core dump file (Ubuntu only)

scylla_setup

Sets up the ScyllaDB configuration. Many of these scripts are included in the setup script.

scylla_stop

Resets network mode if running in virtio or DPDK mode.

scylla_swap_setup

Configures a swap space on the host.

scylla_sysconfig_setup

Rewrites the /etc/sysconfig/scylla file.

ScyllaDB Scripts (Not included with ScyllaDB-Setup)¶

Script Name

Description

node_health_check

Gathers metrics and information on the node, checking that the node is configured correctly.

scylla-blocktune

Tunes the filesystem and block layer (e.g. block size I/O scheduler configuration) for ScyllaDB.

scylla_cpuscaling_setup

Configures the CPU frequency scaling (IOW, puts the CPU in “performance” mode, instead of the slower “powersave” mode).

scylla_cpuset_setup

Configures which CPUs the ScyllaDB server threads run on.

scylla_fstrim

Runs fstrim, which cleans up unused blocks of data from your SSD storage device. It runs automatically if you run scylla_fstrim_set up (see below).

scylla_fstrim_setup

Configures a job so that fstrim runs automatically.

scylla-housekeeping

Checks if there are new versions of ScyllaDB available, and also shares some telemetry information for us to keep track of what versions are installed on the field.

scylla_rsyslog_setup

Configures the “rsyslog” service, which is used to send logs to a remote server.

scylla_selinux_setup

Disables SELinux for ScyllaDB.

Note

It’s important to keep I/O scheduler configuration in sync on nodes with the same hardware. That’s why we recommend skipping running scylla_io_setup when provisioning a new node with exactly the same hardware setup as existing nodes in the cluster.

Instead, we recommend to copy the following files from an existing node to the new node after running scylla_setup and restart scylla-server service (if it is already running):
  • /etc/scylla.d/io.conf

  • /etc/scylla.d/io_properties.yaml

Using different I/O scheduler configuration may result in unnecessary bottlenecks.

Bootloader Settings¶

If ScyllaDB is installed on an Amazon AMI, the bootloader should provide the clocksource=tsc and tsc=reliable options. This enables an accurate, high-resolution Time Stamp Counter (TSC) for setting the system time.

This configuration is provided in the file /usr/lib/scylla/scylla_bootparam_setup.

Remove Crash Reporting Software¶

Remove the apport-noui or abrt packages if present, and set up a location and file name pattern for core dumps.

This configuration is provided in the file /usr/lib/scylla/scylla_bootparam_setup.

Set Up Network Time Synchronization¶

It is highly recommended to enforce time synchronization between ScyllaDB servers.

Run ntpstat on all nodes to check that system time is synchronized. If you are running in a virtualized environment and your system time is set on the host, you may not need to run NTP on the guest. Check the documentation for your platform.

If you have your own time servers shared with an application using ScyllaDB, use the same NTP configuration as for your application servers. The script /usr/lib/scylla/scylla_ntp_setup provides sensible defaults, using Amazon NTP servers if installed on the Amazon cloud, and other pool NTP servers otherwise.

Set Up RAID and Filesystem¶

Setting the file system to XFS is the most important and mandatory for production. ScyllaDB will significantly slow down without it.

The script /usr/lib/scylla/scylla_raid_setup performs the necessary RAID configuration and XFS filesystem creation for ScyllaDB.

Arguments to the script are

  • -d specify disks for RAID

  • -r MD device name for RAID

  • -u update /etc/fstab for RAID

On the ScyllaDB AMI, the RAID configuration is handled automatically in the /usr/lib/scylla/scylla_prepare script.

CPU Pinning¶

When installing ScyllaDB, it is highly recommended to use the scylla_setup script. ScyllaDB should not share CPUs with any CPU consuming process. In addition, when running ScyllaDB on AWS, we recommend pinning all NIC IRQs to CPU0 (due to the same reason). As a result, ScyllaDB should be prevented from running on CPU0 and its hyper-threading siblings. To verify that ScyllaDB is pinning CPU0, use the command below: If the node has four or fewer CPUs, don’t use this option.

To verify:

cat /etc/scylla.d/cpuset.conf

Example output:

--cpuset `1-15,17-31`

Networking¶

To configure networking, we recommend running the perftune.py script with the following parameters:

  • --tune net

  • --nic <your network interface name>

See Seastar Perftune for details.

Configuring ScyllaDB¶

Configuration for ScyllaDB itself is in the ScyllaDB Configuration section of the administration guide.

Development System Configuration¶

The following item is not required in production.

When working on DPDK support for ScyllaDB, enable hugepages.

NR_HUGEPAGES=128
mount -t hugetlbfs -o pagesize=2097152 none /mnt/huge
mount -t hugetlbfs -o pagesize=2097152 none /dev/hugepages/
for n in /sys/devices/system/node/node?; do
    echo $NR_HUGEPAGES > $n/hugepages/hugepages-2048kB/nr_hugepages;
done

Huge page configuration is written to /etc/sysconfig/scylla-server by the script /usr/lib/scylla/sysconfig_setup

Related Topics¶

System Limits - outlines the system limits which should be set or removed.

Getting Started

Was this page helpful?

PREVIOUS
System Configuration
NEXT
ScyllaDB Snitches
  • Create an issue

On this page

  • Configure ScyllaDB
    • System Configuration Files and Scripts
    • ScyllaDB Scripts
    • Bootloader Settings
    • Remove Crash Reporting Software
    • Set Up Network Time Synchronization
    • Set Up RAID and Filesystem
    • CPU Pinning
    • Networking
    • Configuring ScyllaDB
    • Development System Configuration
    • Related Topics
ScyllaDB Enterprise
  • enterprise
    • 2024.2
    • 2024.1
    • 2023.1
    • 2022.2
  • Getting Started
    • Install ScyllaDB Enterprise
      • ScyllaDB Web Installer for Linux
      • Install ScyllaDB Without root Privileges
      • Install scylla-jmx Package
      • Air-gapped Server Installation
      • ScyllaDB Housekeeping and how to disable it
      • ScyllaDB Developer Mode
      • Launch ScyllaDB on AWS
      • Launch ScyllaDB on GCP
      • Launch ScyllaDB on Azure
    • Configure ScyllaDB
    • ScyllaDB Configuration Reference
    • ScyllaDB Requirements
      • System Requirements
      • OS Support
      • Cloud Instance Recommendations
      • ScyllaDB in a Shared Environment
    • Migrate to ScyllaDB
      • Migration Process from Cassandra to ScyllaDB
      • ScyllaDB and Apache Cassandra Compatibility
      • Migration Tools Overview
    • Integration Solutions
      • Integrate ScyllaDB with Spark
      • Integrate ScyllaDB with KairosDB
      • Integrate ScyllaDB with Presto
      • Integrate ScyllaDB with Elasticsearch
      • Integrate ScyllaDB with Kubernetes
      • Integrate ScyllaDB with the JanusGraph Graph Data System
      • Integrate ScyllaDB with DataDog
      • Integrate ScyllaDB with Kafka
      • Integrate ScyllaDB with IOTA Chronicle
      • Integrate ScyllaDB with Spring
      • Shard-Aware Kafka Connector for ScyllaDB
      • Install ScyllaDB with Ansible
      • Integrate ScyllaDB with Databricks
      • Integrate ScyllaDB with Jaeger Server
      • Integrate ScyllaDB with MindsDB
    • Tutorials
  • ScyllaDB for Administrators
    • Administration Guide
    • Procedures
      • Cluster Management
      • Backup & Restore
      • Change Configuration
      • Maintenance
      • Best Practices
      • Benchmarking ScyllaDB
      • Migrate from Cassandra to ScyllaDB
      • Disable Housekeeping
    • Security
      • ScyllaDB Security Checklist
      • Enable Authentication
      • Enable and Disable Authentication Without Downtime
      • Creating a Custom Superuser
      • Generate a cqlshrc File
      • Reset Authenticator Password
      • Enable Authorization
      • Grant Authorization CQL Reference
      • Certificate-based Authentication
      • Role Based Access Control (RBAC)
      • ScyllaDB Auditing Guide
      • Encryption: Data in Transit Client to Node
      • Encryption: Data in Transit Node to Node
      • Generating a self-signed Certificate Chain Using openssl
      • Configure SaslauthdAuthenticator
      • Encryption at Rest
      • LDAP Authentication
      • LDAP Authorization (Role Management)
      • Software Bill Of Materials (SBOM)
    • Admin Tools
      • Nodetool Reference
      • CQLSh
      • Admin REST API
      • Tracing
      • ScyllaDB SStable
      • ScyllaDB Types
      • SSTableLoader
      • cassandra-stress
      • SSTabledump
      • SSTableMetadata
      • ScyllaDB Logs
      • Seastar Perftune
      • Virtual Tables
      • Reading mutation fragments
      • Maintenance socket
      • Maintenance mode
      • Task manager
    • Version Support Policy
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
    • ScyllaDB Manager
    • Upgrade Procedures
      • About Upgrade
      • Upgrade Guides
    • System Configuration
      • System Configuration Guide
      • scylla.yaml
      • ScyllaDB Snitches
    • Benchmarking ScyllaDB
    • ScyllaDB Diagnostic Tools
  • ScyllaDB for Developers
    • Develop with ScyllaDB
    • Tutorials and Example Projects
    • Learn to Use ScyllaDB
    • ScyllaDB Alternator
    • ScyllaDB Drivers
      • ScyllaDB CQL Drivers
      • ScyllaDB DynamoDB Drivers
  • CQL Reference
    • CQLSh: the CQL shell
    • Appendices
    • Compaction
    • Consistency Levels
    • Consistency Level Calculator
    • Data Definition
    • Data Manipulation
      • SELECT
      • INSERT
      • UPDATE
      • DELETE
      • BATCH
    • Data Types
    • Definitions
    • Global Secondary Indexes
    • Expiring Data with Time to Live (TTL)
    • Functions
    • Wasm support for user-defined functions
    • JSON Support
    • Materialized Views
    • Non-Reserved CQL Keywords
    • Reserved CQL Keywords
    • DESCRIBE SCHEMA
    • Service Levels
    • ScyllaDB CQL Extensions
  • Features
    • Lightweight Transactions
    • Global Secondary Indexes
    • Local Secondary Indexes
    • Materialized Views
    • Counters
    • Change Data Capture
      • CDC Overview
      • The CDC Log Table
      • Basic operations in CDC
      • CDC Streams
      • CDC Stream Generations
      • Querying CDC Streams
      • Advanced column types
      • Preimages and postimages
      • Data Consistency in CDC
    • Workload Attributes
    • Workload Prioritization
  • ScyllaDB Architecture
    • Data Distribution with Tablets
    • ScyllaDB Ring Architecture
    • ScyllaDB Fault Tolerance
    • Consistency Level Console Demo
    • ScyllaDB Anti-Entropy
      • ScyllaDB Hinted Handoff
      • ScyllaDB Read Repair
      • ScyllaDB Repair
    • SSTable
      • ScyllaDB SSTable - 2.x
      • ScyllaDB SSTable - 3.x
    • Compaction Strategies
    • Raft Consensus Algorithm in ScyllaDB
    • Zero-token Nodes
  • Troubleshooting ScyllaDB
    • Errors and Support
      • Report a ScyllaDB problem
      • Error Messages
      • Change Log Level
    • ScyllaDB Startup
      • Ownership Problems
      • ScyllaDB will not Start
      • ScyllaDB Python Script broken
    • Upgrade
      • Inaccessible configuration files after ScyllaDB upgrade
    • Cluster and Node
      • Handling Node Failures
      • Failure to Add, Remove, or Replace a Node
      • Failed Decommission Problem
      • Cluster Timeouts
      • Node Joined With No Data
      • NullPointerException
      • Failed Schema Sync
    • Data Modeling
      • ScyllaDB Large Partitions Table
      • ScyllaDB Large Rows and Cells Table
      • Large Partitions Hunting
      • Failure to Update the Schema
    • Data Storage and SSTables
      • Space Utilization Increasing
      • Disk Space is not Reclaimed
      • SSTable Corruption Problem
      • Pointless Compactions
      • Limiting Compaction
    • CQL
      • Time Range Query Fails
      • COPY FROM Fails
      • CQL Connection Table
    • ScyllaDB Monitor and Manager
      • Manager and Monitoring integration
      • Manager lists healthy nodes as down
    • Installation and Removal
      • Removing ScyllaDB on Ubuntu breaks system packages
  • Knowledge Base
    • Upgrading from experimental CDC
    • Compaction
    • Consistency in ScyllaDB
    • Counting all rows in a table is slow
    • CQL Query Does Not Display Entire Result Set
    • When CQLSh query returns partial results with followed by “More”
    • Run ScyllaDB and supporting services as a custom user:group
    • Customizing CPUSET
    • Decoding Stack Traces
    • Snapshots and Disk Utilization
    • DPDK mode
    • Debug your database with Flame Graphs
    • Efficient Tombstone Garbage Collection in ICS
    • How to Change gc_grace_seconds for a Table
    • Gossip in ScyllaDB
    • Increase Permission Cache to Avoid Non-paged Queries
    • How does ScyllaDB LWT Differ from Apache Cassandra ?
    • Map CPUs to ScyllaDB Shards
    • ScyllaDB Memory Usage
    • NTP Configuration for ScyllaDB
    • Updating the Mode in perftune.yaml After a ScyllaDB Upgrade
    • POSIX networking for ScyllaDB
    • ScyllaDB consistency quiz for administrators
    • Recreate RAID devices
    • How to Safely Increase the Replication Factor
    • ScyllaDB and Spark integration
    • Increase ScyllaDB resource limits over systemd
    • ScyllaDB Seed Nodes
    • How to Set up a Swap Space
    • ScyllaDB Snapshots
    • ScyllaDB payload sent duplicated static columns
    • Stopping a local repair
    • System Limits
    • How to flush old tombstones from a table
    • Time to Live (TTL) and Compaction
    • ScyllaDB Nodes are Unresponsive
    • Update a Primary Key
    • Using the perf utility with ScyllaDB
    • Configure ScyllaDB Networking with Multiple NIC/IP Combinations
  • Reference
    • AWS Images
    • Azure Images
    • GCP Images
    • Configuration Parameters
    • Glossary
    • Limits
    • ScyllaDB Enterprise vs. Open Source Matrix
    • API Reference (BETA)
    • Metrics (BETA)
  • ScyllaDB University
  • ScyllaDB FAQ
  • Alternator: DynamoDB API in Scylla
    • Getting Started With ScyllaDB Alternator
    • ScyllaDB Alternator for DynamoDB users
    • Alternator-specific APIs
Docs Tutorials University Contact Us About Us
© 2025, ScyllaDB. All rights reserved. | Terms of Service | Privacy Policy | ScyllaDB, and ScyllaDB Cloud, are registered trademarks of ScyllaDB, Inc.
Last updated on 09 Apr 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.6