diff --git a/docs/operating-scylla/security/authentication.rst b/docs/operating-scylla/security/authentication.rst index 9f979072e5..ed438331bb 100644 --- a/docs/operating-scylla/security/authentication.rst +++ b/docs/operating-scylla/security/authentication.rst @@ -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 ` 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 ` for instructions. + cqlsh #. If you want to create users and roles, continue to :doc:`Enable Authorization `. diff --git a/docs/operating-scylla/security/create-superuser.rst b/docs/operating-scylla/security/create-superuser.rst index f94d726399..17e5bc11e4 100644 --- a/docs/operating-scylla/security/create-superuser.rst +++ b/docs/operating-scylla/security/create-superuser.rst @@ -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 ` +- :ref:`Using an existing superuser account to create a new superuser role ` -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 `. +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 WITH SUPERUSER = true AND LOGIN = true and 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 -p - - 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 ` 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 `. -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: - auth_superuser_salted_password: +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 - * If any superuser other than ``cassandra`` is already defined in the cluster. - * After you create a custom superuser with the CQL :ref:`procedure `. +Replace ```` with the socket path configured in ``scylla.yaml``. + +2. Create new superuser role using ``CREATE ROLE`` command. + +.. code-block:: cql + + CREATE ROLE WITH SUPERUSER = true AND LOGIN = true and PASSWORD = ''; + +3. Verify that you can log in to your node using ``cqlsh`` command with the new password. + +.. code-block:: shell + + cqlsh -u + Password: + +.. note:: + + Enter the value of `` 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 WITH SUPERUSER = true AND LOGIN = true and PASSWORD = ''; + +3. Verify that you can log in to your node using ``cqlsh`` command with the new password. + +.. code-block:: shell + + cqlsh -u + Password: + +.. note:: + + Enter the value of `` 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; diff --git a/docs/operating-scylla/security/enable-authorization.rst b/docs/operating-scylla/security/enable-authorization.rst index 87fec06dc2..a4c92c6522 100644 --- a/docs/operating-scylla/security/enable-authorization.rst +++ b/docs/operating-scylla/security/enable-authorization.rst @@ -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 ` 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 ` 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 `. - -.. _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 --------------------- diff --git a/docs/operating-scylla/security/index.rst b/docs/operating-scylla/security/index.rst index 7dafb516c1..8964fa105a 100644 --- a/docs/operating-scylla/security/index.rst +++ b/docs/operating-scylla/security/index.rst @@ -38,7 +38,7 @@ Security * :doc:`Enable Authentication ` * :doc:`Enable and Disable Authentication Without Downtime ` - * :doc:`Creating a Custom Superuser ` + * :doc:`Creating a Superuser ` * :doc:`Generate a cqlshrc File ` * :doc:`Enable Authorization` * :doc:`Role Based Access Control (RBAC) ` diff --git a/docs/operating-scylla/security/runtime-authentication.rst b/docs/operating-scylla/security/runtime-authentication.rst index 1c05713eea..348e1021fc 100644 --- a/docs/operating-scylla/security/runtime-authentication.rst +++ b/docs/operating-scylla/security/runtime-authentication.rst @@ -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 ` 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 diff --git a/docs/troubleshooting/password-reset.rst b/docs/troubleshooting/password-reset.rst index c3af3a2cad..4cf60c9787 100644 --- a/docs/troubleshooting/password-reset.rst +++ b/docs/troubleshooting/password-reset.rst @@ -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 ` 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 ` 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 -| 2. Remove system tables starting with ``role`` prefix from ``/var/lib/scylla/data/system`` directory. +Replace ```` 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