mirrors/scylladb
1
0
Fork 0
mirror of https://github.com/scylladb/scylladb.git synced 2026-05-12 19:02:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update documentation related to default superuser

Browse Source 
Update create superuser procedure:
- Remove notes about default `cassandra` superuser
- Add create superuser using existing superuser section
- Update create superuser by using `scylla.yaml` config
- Add create superuser using maintenance socket

Update password reset procedure:
- Add maintenance socket approach
- Remove the old approach with deleting all the roles

Update enabling authentication with downtime and during runtime:
- Mention creating new superuser over the maintenance socket
- Remove default superuser usage

Update enable authorization:
- Mention creating new superuser over the maintenance socket
- Remove mention of default superuser

Reasoning for deletion of the old approach:
- [old] Needs cluster downtime, removes all roles, needs recreation of roles,
  needs maintenance socket anyways, if config values are not used for superuser
- [new] No cluster downtime, possibly one node restart to enable maintenance
  socket, faster

Refs SCYLLADB-409
This commit is contained in:
Dario Mirovic
2025-11-25 10:51:48 +01:00
parent 3db74aaf5f
commit afafb8a8fa
6 changed files with 125 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/operating-scylla/security/authentication.rst
View File

@@ -19,21 +19,15 @@ Procedure
authenticator: PasswordAuthenticator
#. Restart ScyllaDB.
#. Restart ScyllaDB.
.. include:: /rst_include/scylla-commands-restart-index.rst
#. Start cqlsh with the default superuser username and password.
#. Start cqlsh over the maintenance socket and create a new superuser. See :ref:`Setting Up a Superuser Using the Maintenance Socket <create-superuser-using-maintenance-socket>` for instructions.
.. code-block:: cql
cqlsh -u cassandra -p cassandra
.. note::
Before proceeding to the next step, we recommend creating a custom superuser
to improve security.
See :doc:`Creating a Custom Superuser </operating-scylla/security/create-superuser/>` for instructions.
cqlsh <maintenance_socket_path>
#. If you want to create users and roles, continue to :doc:`Enable Authorization </operating-scylla/security/enable-authorization>`.

170
docs/operating-scylla/security/create-superuser.rst
View File

@@ -1,111 +1,95 @@
================================
Creating a Custom Superuser
Creating a Superuser
================================
The default ScyllaDB superuser role is ``cassandra`` with password ``cassandra``.
Users with the ``cassandra`` role have full access to the database and can run
There is no default superuser role in ScyllaDB.
Users with a superuser role have full access to the database and can run
any CQL command on the database resources.
To improve security, we recommend creating a custom superuser. You should:
There are two ways you can create a superuser in ScyllaDB:
#. Use the default ``cassandra`` superuser to log in.
#. Create a custom superuser.
#. Log in as the custom superuser.
#. Remove the ``cassandra`` role.
- :ref:`Using the ScyllaDB Maintenance Socket to create a superuser role <create-superuser-using-maintenance-socket>`
- :ref:`Using an existing superuser account to create a new superuser role <create-superuser-using-existing-superuser>`
In the above procedure, you only need to use the ``cassandra`` superuser once, during
the initial RBAC set up.
To completely eliminate the need to use ``cassandra``, you can :ref:`configure the initial
custom superuser in the scylla.yaml configuration file <create-superuser-in-config-file>`.
When setting up a new cluster, use the maintenance socket approach to create the first superuser.
.. _create-superuser-procedure:
Procedure
-----------
.. _create-superuser-using-maintenance-socket:
#. Start cqlsh with the default superuser settings:
.. code::
cqlsh -u cassandra -p cassandra
#. Create a new superuser:
.. code::
CREATE ROLE <custom_superuser name> WITH SUPERUSER = true AND LOGIN = true and PASSWORD = '<custom_superuser_password>';
For example:
.. code::
:class: hide-copy-button
CREATE ROLE dba WITH SUPERUSER = true AND LOGIN = true and PASSWORD = '39fksah!';
.. warning::
You must set a PASSWORD when creating a role with LOGIN privileges.
Otherwise, you will not be able to log in to the database using that role.
#. Exit cqlsh:
.. code::
EXIT;
#. Log in as the new superuser:
.. code::
cqlsh -u <custom_superuser name> -p <custom_superuser_password>
For example:
.. code::
:class: hide-copy-button
cqlsh -u dba -p 39fksah!
#. Show all the roles to verify that the new superuser was created:
.. code::
LIST ROLES;
#. Remove the cassandra superuser:
.. code::
DROP ROLE cassandra;
#. Show all the roles to verify that the cassandra role was deleted:
.. code::
LIST ROLES;
.. _create-superuser-in-config-file:
Setting Custom Superuser Credentials in scylla.yaml
Setting Up a Superuser Using the Maintenance Socket
------------------------------------------------------
Operating ScyllaDB using the default superuser ``cassandra`` with password ``cassandra``
is insecure and impacts performance. For this reason, the default should be used only once -
to create a custom superuser role, following the CQL :ref:`procedure <create-superuser-procedure>` above.
If no superuser account exists in the cluster, which is the case for new clusters, you can create a superuser using the ScyllaDB Maintenance Socket.
In order to do that, the node must have the maintenance socket enabled.
See :doc:`Admin Tools: Maintenance Socket </operating-scylla/admin-tools/maintenance-socket/>`.
To avoid executing with the default credentials for the period before you can make
the CQL modifications, you can configure the custom superuser name and password
in the ``scylla.yaml`` configuration file:
To create a superuser using the maintenance socket, you should:
.. code-block:: yaml
auth_superuser_name: <superuser name>
auth_superuser_salted_password: <superuser salted password as processed by mkpassword or similar - cleartext is not allowed>
1. Connect to the node using ``cqlsh`` over the maintenance socket.
.. caution::
.. code-block:: shell
The superuser credentials in the ``scylla.yaml`` file will be ignored:
cqlsh <maintenance_socket_path>
* If any superuser other than ``cassandra`` is already defined in the cluster.
* After you create a custom superuser with the CQL :ref:`procedure <create-superuser-procedure>`.
Replace ``<maintenance_socket_path>`` with the socket path configured in ``scylla.yaml``.
2. Create new superuser role using ``CREATE ROLE`` command.
.. code-block:: cql
CREATE ROLE <new_superuser> WITH SUPERUSER = true AND LOGIN = true and PASSWORD = '<new_superuser_password>';
3. Verify that you can log in to your node using ``cqlsh`` command with the new password.
.. code-block:: shell
cqlsh -u <new_superuser>
Password:
.. note::
Enter the value of `<new_superuser_password>` password when prompted. The input is not displayed.
4. Show all the roles to verify that the new superuser was created:
.. code-block:: cql
LIST ROLES;
.. _create-superuser-using-existing-superuser:
Setting Up a Superuser Using an Existing Superuser Account
-------------------------------------------------------------
To create a superuser using an existing superuser account, you should:
1. Log in to cqlsh using an existing superuser account.
.. code-block:: shell
cqlsh -u existing_superuser -p existing_superuser_password
2. Create a new superuser.
.. code-block:: cql
CREATE ROLE <new_superuser> WITH SUPERUSER = true AND LOGIN = true and PASSWORD = '<new_superuser_password>';
3. Verify that you can log in to your node using ``cqlsh`` command with the new password.
.. code-block:: shell
cqlsh -u <new_superuser>
Password:
.. note::
Enter the value of `<new_superuser_password>` password when prompted. The input is not displayed.
4. Show all the roles to verify that the new superuser was created:
.. code-block:: cql
LIST ROLES;

37
docs/operating-scylla/security/enable-authorization.rst
View File

@@ -28,7 +28,6 @@ The following assumes that Authentication has already been enabled via the proce
2. Set your credentials as the `superuser`_
3. Login to cqlsh as the superuser and set `roles`_ and privileges for your users
4. Confirm users can `access`_ the client with their new credentials.
5. `Remove`_ Cassandra default user / passwords
.. _authorizer:
@@ -51,19 +50,11 @@ It is highly recommended to perform this action on a node that is not processing
.. _superuser:
Set a Superuser
Create a Superuser
.........................
The default ScyllaDB superuser role is ``cassandra`` with password ``cassandra``. Using the default
superuser is unsafe and may significantly impact performance.
If you haven't created a custom superuser while enabling authentication, you should create a custom superuser
before creating additional roles.
See :doc:`Creating a Custom Superuser </operating-scylla/security/create-superuser/>` for instructions.
.. note::
We recommend creating a custom superuser to improve security.
There is no default superuser in ScyllaDB. You should create a superuser before creating additional roles.
See :doc:`Creating a Superuser </operating-scylla/security/create-superuser/>` for instructions.
.. _roles:
@@ -110,30 +101,8 @@ The following should be noted:
* When initiating a connection, clients will need to use the user name and password that you assign
* Confirm all clients can connect before removing the Cassandra default password and user.
2. To remove permission from any role or user, see :ref:`REVOKE PERMISSION <revoke-permission-statement>`.
.. _remove:
Remove Cassandra Default Password and User
..........................................
To prevent others from entering with the old superuser password, you can and should delete it.
.. code-block:: cql
DROP ROLE [ IF EXISTS ] 'old-username';
For example
.. code-block:: cql
DROP ROLE [ IF EXISTS ] 'cassandra';
Additional References
---------------------

2
docs/operating-scylla/security/index.rst
View File

@@ -38,7 +38,7 @@ Security
* :doc:`Enable Authentication </operating-scylla/security/authentication/>`
* :doc:`Enable and Disable Authentication Without Downtime </operating-scylla/security/runtime-authentication/>`
* :doc:`Creating a Custom Superuser </operating-scylla/security/create-superuser/>`
* :doc:`Creating a Superuser </operating-scylla/security/create-superuser/>`
* :doc:`Generate a cqlshrc File <gen-cqlsh-file>`
* :doc:`Enable Authorization</operating-scylla/security/enable-authorization/>`
* :doc:`Role Based Access Control (RBAC) </operating-scylla/security/rbac-usecase/>`

21
docs/operating-scylla/security/runtime-authentication.rst
View File

@@ -25,20 +25,19 @@ Procedure
.. include:: /rst_include/scylla-commands-restart-index.rst
#. Login with the default superuser credentials and create an authenticated user with strong password.
#. Login over the maintenance socket and create an authenticated user with strong password.
For example:
See :ref:`Setting Up a Superuser Using the Maintenance Socket <create-superuser-using-maintenance-socket>` for instructions.
.. code-block:: cql
cqlsh -ucassandra -pcassandra
cqlsh /path/to/maintenance/socket/cql.m
cassandra@cqlsh> CREATE ROLE scylla WITH PASSWORD = '123456' AND LOGIN = true AND SUPERUSER = true;
cassandra@cqlsh> LIST ROLES;
name |super
----------+-------
cassandra |True
scylla |True
Optionally, assign the role to your user. For example:
@@ -47,20 +46,6 @@ Procedure
cassandra@cqlsh> GRANT scylla TO myuser
#. Login with the new user created and drop the superuser cassandra.
.. code-block:: cql
cqlsh -u scylla -p 123456
scylla@cqlsh> DROP ROLE cassandra;
scylla@cqlsh> LIST ROLES;
name |super
----------+-------
scylla |True
#. Update the ``authenticator`` parameter in ``scylla.yaml`` for all the nodes in the cluster: Change ``authenticator: com.scylladb.auth.TransitionalAuthenticator`` to ``authenticator: PasswordAuthenticator``.
.. code-block:: yaml

59
docs/troubleshooting/password-reset.rst
View File

@@ -1,37 +1,54 @@
Reset Authenticator Password
============================
This procedure describes what to do when a user loses his password and can not reset it with a superuser role.
The procedure requires cluster downtime and as a result, all auth data is deleted.
This procedure describes what to do when a user loses their password and can not reset it with a superuser role.
If a node has maintenance socket available, there is no node or cluster downtime required.
If a node does not have maintenance socket available, node has to be restarted with maintenance socket enabled, but no cluster downtime is required.
Prerequisites
.............
Enable maintenance socket on the node. If already done, skip to the ``Procedure`` section.
To check if the maintenance socket is enabled, see :doc:`Admin Tools: Maintenance Socket </operating-scylla/admin-tools/maintenance-socket/>` for details.
1. Stop the ScyllaDB node.
.. code-block:: shell
sudo systemctl stop scylla-server
2. Edit ``/etc/scylla/scylla.yaml`` file and configure the maintenance socket.
See :doc:`Admin Tools: Maintenance Socket </operating-scylla/admin-tools/maintenance-socket/>` for details.
3. Start the ScyllaDB node.
.. code-block:: shell
sudo systemctl start scylla-server
Procedure
.........
| 1. Stop ScyllaDB nodes (**Stop all the nodes in the cluster**).
1. Connect to the node using ``cqlsh`` over the maintenance socket.
.. code-block:: shell
.. code-block:: shell
sudo systemctl stop scylla-server
cqlsh <maintenance_socket_path>
| 2. Remove system tables starting with ``role`` prefix from ``/var/lib/scylla/data/system`` directory.
Replace ``<maintenance_socket_path>`` with the socket path configured in ``scylla.yaml``.
.. code-block:: shell
rm -rf /var/lib/scylla/data/system/role*
| 3. Start ScyllaDB nodes.
.. code-block:: shell
sudo systemctl start scylla-server
| 4. Verify that you can log in to your node using ``cqlsh`` command.
| The access is only possible using ScyllaDB superuser.
2. Reset the password for the user using ``ALTER ROLE`` command.
.. code-block:: cql
cqlsh -u cassandra -p cassandra
| 5. Recreate the users
ALTER ROLE username WITH PASSWORD 'new_password';
3. Verify that you can log in to your node using ``cqlsh`` command with the new password.
.. code-block:: shell
cqlsh -u username -p new_password
.. include:: /troubleshooting/_common/ts-return.rst