From: Shweta Bhosale Date: Fri, 16 Jan 2026 07:49:06 +0000 (+0530) Subject: doc: Documentation for ssh hardening X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=ee528dbf218800dded06bab7c0324cd71804dbe7;p=ceph-ci.git doc: Documentation for ssh hardening Fixes: https://tracker.ceph.com/issues/74045 Signed-off-by: Shweta Bhosale --- diff --git a/doc/cephadm/host-management.rst b/doc/cephadm/host-management.rst index 686a085cb5e..7a03818f59a 100644 --- a/doc/cephadm/host-management.rst +++ b/doc/cephadm/host-management.rst @@ -551,8 +551,29 @@ cephadm operations. Run a command of the following form: ceph cephadm set-user -Prior to running this, the cluster SSH key needs to be added to this user's -``authorized_keys`` file and non-root users must have passwordless sudo access. +The ``set-user`` command automatically configures the specified user on all cluster +hosts by calling ``cephadm setup-ssh-user`` on each host. This command is available starting +with the Umbrella release and includes the following: + +- Setting up passwordless sudo access for non-root users +- Authorizing the cluster's SSH public key for the user + +If you have already manually configured the user on all hosts, you can skip +the automatic setup by using the ``--skip-pre-steps`` flag: + +.. prompt:: bash # + + ceph cephadm set-user --skip-pre-steps + +For manual setup of SSH users on individual hosts, you can use the +``cephadm setup-ssh-user`` command directly: + +.. prompt:: bash # + + cephadm setup-ssh-user --ssh-user --ssh-pub-key + +This command validates that the user exists, configures passwordless sudo access, +and authorizes the SSH public key. Customizing the SSH Configuration @@ -668,6 +689,94 @@ when executing ``ceph * metadata``. This in turn means cephadm also requires the bare host name when adding a host to the cluster: ``ceph orch host add ``. -.. - TODO: This chapter needs to provide way for users to configure - Grafana in the dashboard, as this is right now very hard to do. +Sudo Hardening +============= + +Cephadm supports sudo hardening to enhance security by restricting sudo privilege +escalation for non-root SSH users. When sudo hardening is enabled, cephadm uses the +``cephadm_invoker.py`` script to securely execute cephadm commands with controlled +privilege escalation. + +Enabling Sudo Hardening +---------------------- + +To enable sudo hardening for the entire cluster, use the following command: + +.. prompt:: bash # + + ceph cephadm prepare-host-and-enable-sudo-hardening + +This command performs a comprehensive sudo hardening setup: + +1. **Host Preparation**: Prepares all cluster hosts for sudo hardening by: + - Installing/upgrading cephadm RPM with the invoker script + - Configuring restricted sudo access for non-root users + - Setting up SSH key authorization + +2. **SSH User Configuration**: Sets the specified user for cluster SSH operations + +3. **Global Enablement**: Enables sudo hardening cluster-wide + +The ```` parameter specifies which non-root user should be configured for SSH access. +This user will have restricted sudo access configured through the sudoers file. + +You can manually prepare a host for sudo hardening using: + +.. prompt:: bash # + + cephadm prepare-host-sudo-hardening --ssh-user --ssh-pub-key + +.. note:: During initial host addition, the root user is used for setup. After + Sudo hardening is enabled, the specified non-root user with restricted sudo + access will be used for ongoing operations. + +Sudo Hardening Workflow +---------------------- + +When sudo hardening is enabled, the following workflow is used: + +1. **Host Addition**: When adding a new host with ``ceph orch host add``, cephadm + automatically prepares the host for sudo hardening +2. **Command Execution**: Instead of executing cephadm directly, commands are + routed through ``cephadm_invoker.py`` +3. **Binary Verification**: The invoker validates the cephadm binary's hash before execution +4. **Secure Execution**: Commands are executed with restricted permissions + +The ``cephadm_invoker.py`` script provides the following subcommands: + +- ``run``: Execute cephadm binary with hash verification +- ``deploy_cephadm_binary``: Deploy cephadm binary to final location +- ``check_existence``: Check if a file exists + +Sudo Access Restrictions +------------------------- + +Sudo hardening restricts sudo access for non-root users to enhance security. When a +host is prepared for sudo hardening, the sudoers configuration is modified to limit +the commands that can be executed with sudo. This prevents unauthorized command +execution while still allowing necessary cephadm operations. + +The sudoers configuration restricts access to only the ``cephadm_invoker.py`` script +and essential system commands, providing a secure execution environment. + +Security Benefits +----------------- +Sudo hardening provides the following security benefits: + +1. The invoker validates the cephadm binary's hash +2. If validation fails, it signals for binary redeployment +3. Commands are executed with restricted sudo permissions +4. All operations are logged for security auditing + + +Disabling Sudo Hardening +----------------------- + +To disable sudo hardening: + +.. prompt:: bash # + + ceph config set mgr mgr/cephadm/sudo_hardening false + +.. note:: Disabling sudo hardening does not automatically revert host configurations. + Hosts that were prepared for sudo hardening will retain the invoker setup. diff --git a/doc/dev/cephadm/cephadm-invoker.rst b/doc/dev/cephadm/cephadm-invoker.rst new file mode 100644 index 00000000000..930b2af85d6 --- /dev/null +++ b/doc/dev/cephadm/cephadm-invoker.rst @@ -0,0 +1,58 @@ +Cephadm Invoker +=============== + +The ``cephadm_invoker.py`` script provides a wrapper intended for executing +cephadm commands with limited sudo priviliges. It is used when sudo hardening +is enabled. + +Overview +-------- + +The cephadm invoker validates the cephadm binary hash before execution and +provides a secure way to run cephadm commands and deploy binaries. It is installed as +part of the cephadm RPM at ``/usr/libexec/cephadm_invoker.py``. + +Commands +-------- + +The invoker supports the following subcommands: + +``run`` + +Execute cephadm binary with arguments after hash verification:: + + cephadm_invoker.py run [args...] + +The binary path must include a hash in the filename for verification. + +``deploy_binary`` + +Deploy cephadm binary from a temporary file to the final location:: + + cephadm_invoker.py deploy_binary + +``check_binary`` + +Check if a cephadm binary exists:: + + cephadm_invoker.py check_binary + +Returns exit code 0 if the file exists, 2 if it does not exist. + +Exit Codes +---------- + +- ``0``: Success +- ``1``: General error (file not found, permission issues, etc.) +- ``2``: Binary hash mismatch or file doesn't exist (triggers redeployment) +- ``126``: Permission denied during execution + +Security Features +----------------- + +The cephadm invoker provides the following security features: + +- **Binary Hash Verification**: Validates the cephadm binary integrity before execution +- **Restricted Execution**: Only allows execution of verified cephadm binaries +- **Secure Deployment**: Safely deploys cephadm binaries with proper permissions +- **Logging**: Comprehensive logging to both console and syslog for audit trails diff --git a/doc/dev/cephadm/index.rst b/doc/dev/cephadm/index.rst index f89e7ed262c..330eeefb059 100644 --- a/doc/dev/cephadm/index.rst +++ b/doc/dev/cephadm/index.rst @@ -11,5 +11,6 @@ CEPHADM Developer Documentation developing-cephadm host-maintenance compliance-check + cephadm-invoker Storage devices and OSDs management <./design/storage_devices_and_osds> scalability-notes diff --git a/doc/man/8/cephadm.rst b/doc/man/8/cephadm.rst index 0a42850bd59..aad82c603f3 100644 --- a/doc/man/8/cephadm.rst +++ b/doc/man/8/cephadm.rst @@ -13,7 +13,7 @@ Synopsis | [--log-dir LOG_DIR] [--logrotate-dir LOGROTATE_DIR] | [--unit-dir UNIT_DIR] [--verbose] [--timeout TIMEOUT] | [--retry RETRY] [--no-container-init] -| {version,pull,inspect-image,ls,list-networks,adopt,rm-daemon,rm-cluster,run,shell,enter,ceph-volume,unit,logs,bootstrap,deploy,check-host,prepare-host,add-repo,rm-repo,install,list-images,update-osd-service} +| {version,pull,inspect-image,ls,list-networks,adopt,rm-daemon,rm-cluster,run,shell,enter,ceph-volume,unit,logs,bootstrap,deploy,check-host,prepare-host,prepare-host-sudo-hardening,setup-ssh-user,add-repo,rm-repo,install,list-images,update-osd-service,exec} | ... @@ -414,6 +414,65 @@ Arguments: * [--expect-hostname EXPECT_HOSTNAME] Set hostname +exec +---- + +Execute a shell command on a cluster host:: + + cephadm exec -- ls -la + +Positional arguments: + +* [command] command to execute + +Arguments: + +* [--timeout TIMEOUT] timeout in seconds (default: None) + + +prepare-host-sudo-hardening +-------------------------- + +Prepare a host for sudo hardening by authorizing SSH keys, installing/upgrading +the cephadm package, and setting up restricted sudoers permissions:: + + cephadm prepare-host-sudo-hardening --ssh-user cephadm --ssh-pub-key + +This command performs the following steps: + +1. Authorizes the provided SSH public key for the specified user +2. Installs or upgrades the cephadm package to match the cluster version (includes cephadm_invoker.py) +3. Sets up sudoers with restricted permissions for cephadm_invoker.py + +Arguments: + +* [--ssh-user SSH_USER] SSH user for key authorization (default: root) +* [--ssh-pub-key SSH_PUB_KEY] SSH public key to authorize +* [--cephadm-version VERSION] Specific cephadm version to install + + +setup-ssh-user +-------------- + +Setup SSH user with passwordless sudo and SSH key authorization:: + + cephadm setup-ssh-user --ssh-user cephadm --ssh-pub-key + +This command configures an SSH user for cephadm operations by: + +1. Validating that the user exists on the system +2. Setting up passwordless sudo for the user (skipped for root) +3. Authorizing the SSH public key for the user + +This command is automatically called by ``ceph cephadm set-user`` to configure +SSH users across all cluster hosts. + +Arguments: + +* [--ssh-user SSH_USER] SSH user to setup (required) +* [--ssh-pub-key SSH_PUB_KEY] SSH public key to add to user's authorized_keys (required) + + pull ----