diff --git a/docs/auth/ssh-connection.rst b/docs/auth/ssh-connection.rst
--- a/docs/auth/ssh-connection.rst
+++ b/docs/auth/ssh-connection.rst
@@ -3,127 +3,136 @@
SSH Connection
--------------
-If you wish to connect to your Git or Mercurial |repos| using SSH, use the
+If you wish to connect to your |repos| using SSH protocol, use the
following instructions.
-.. note::
+1. Include |RCE| generated `authorized_keys` file into your sshd_config.
- SSH access with full |RCE| permissions will require an Admin |authtoken|.
+ By default a file `authorized_keys_rhodecode` is created containing
+ configuration and all allowed user connection keys are stored inside.
+ On each change of stored keys inside |RCE| this file is updated with
+ proper data.
- You need to install the |RC| SSH tool on the server which is running
- the |RCE| instance.
+ .. code-block:: bash
-1. Gather the following information about the instance you wish to connect to:
+ # Edit sshd_config file most likely at /etc/ssh/sshd_config
+ # add or edit the AuthorizedKeysFile, and set to use custom files
+
+ AuthorizedKeysFile %h/.ssh/authorized_keys %h/.ssh/authorized_keys_rhodecode
- * *Hostname*: Use the ``rccontrol status`` command to view instance details.
- * *API key*: From the |RCE|, go to
- :menuselection:`username --> My Account --> Auth Tokens`
- * *Configuration file*: Identify the configuration file for that instance,
- the default is :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
- * Identify which |git| and |hg| packages your |RCM| instance is using.
+ This way we use a separate file for SSH access and separate one for
+ SSH access to |RCE| repositories.
+
+
+2. Enable the SSH module on instance.
- * For |git|, see
- :menuselection:`Admin --> Settings --> System Info`
- * For |hg|, use the ``which hg`` command.
+ On the server where |RCE| is running executing:
+
+ .. code-block:: bash
-2. Clone the |RC| SSH script,
- ``hg clone https://code.rhodecode.com/rhodecode-ssh``
-3. Copy the ``sshwrapper.sample.ini``, and save it as ``sshwrapper.ini``
-4. Configure the :file:`sshwrapper.ini` file using the following example:
+ rccontrol enable-module ssh {instance-id}
-.. code-block:: ini
+ This will add the following configuration into :file:`rhodecode.ini`.
+ This also can be done manually:
- [api]
- host=http://localhost:10005
- key=24a67076d69c84670132f55166ac79d1faafd660
+ .. code-block:: ini
- [shell]
- shell=/bin/bash -l
+ ############################################################
+ ### SSH Support Settings ###
+ ############################################################
- [vcs]
- root=/path/to/repos/
+ ## Defines if a custom authorized_keys file should be created and written on
+ ## any change user ssh keys. Setting this to false also disables posibility
+ ## of adding SSH keys by users from web interface. Super admins can still
+ ## manage SSH Keys.
+ ssh.generate_authorized_keyfile = true
- [rhodecode]
- config=/home/user/.rccontrol/enterprise-3/rhodecode.ini
-
- [vcs:hg]
- path=/usr/bin/hg
+ ## Options for ssh, default is `no-pty,no-port-forwarding,no-X11-forwarding,no-agent-forwarding`
+ # ssh.authorized_keys_ssh_opts =
- # should be a base dir for all git binaries, i.e. not ../bin/git
- [vcs:git]
- path=/usr/bin
-
- [keys]
- path=/home/user/.ssh/authorized_keys
+ ## Path to the authrozied_keys file where the generate entries are placed.
+ ## It is possible to have multiple key files specified in `sshd_config` e.g.
+ ## AuthorizedKeysFile %h/.ssh/authorized_keys %h/.ssh/authorized_keys_rhodecode
+ ssh.authorized_keys_file_path = ~/.ssh/authorized_keys_rhodecode
-5. Add the public key to your |RCE| instance server using the
- :file:`addkey.py` script. This script automatically creates
- the :file:`authorized_keys` file which was specified in your
- :file:`sshwrapper.ini` configuration. Use the following example:
+ ## Command to execute the SSH wrapper. The binary is available in the
+ ## rhodecode installation directory.
+ ## e.g ~/.rccontrol/community-1/profile/bin/rc-ssh-wrapper
+ ssh.wrapper_cmd = ~/.rccontrol/community-1/rc-ssh-wrapper
-.. code-block:: bash
+ ## Allow shell when executing the ssh-wrapper command
+ ssh.wrapper_cmd_allow_shell = false
- $ ./addkey.py --user username --shell --key /home/username/.ssh/id_rsa.pub
-
-.. important::
+ ## Enables logging, and detailed output send back to the client during SSH
+ ## operations. Usefull for debugging, shouldn't be used in production.
+ ssh.enable_debug_logging = false
- To give SSH access to all users, you will need to maintain
- each users |authtoken| in the :file:`authorized_keys` file.
+ ## Paths to binary executable, by default they are the names, but we can
+ ## override them if we want to use a custom one
+ ssh.executable.hg = ~/.rccontrol/vcsserver-1/profile/bin/hg
+ ssh.executable.git = ~/.rccontrol/vcsserver-1/profile/bin/git
+ ssh.executable.svn = ~/.rccontrol/vcsserver-1/profile/bin/svnserve
-6. Connect to your server using SSH from your local machine.
-
-.. code-block:: bash
- $ ssh user@localhost
- Enter passphrase for key '/home/username/.ssh/id_rsa':
+3. Set base_url for instance to enable proper event handling (Optional):
-If you need to manually configure the ``authorized_keys`` file,
-add a line for each key using the following example:
+ If you wish to have integrations working correctly via SSH please configure
+ The Application base_url.
-.. code-block:: vim
+ Use the ``rccontrol status`` command to view instance details.
+ Hostname is required for the integration to properly set the instance URL.
- command="/home/user/.rhodecode-ssh/sshwrapper.py --user username --shell",
- no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-rsa yourpublickey
+ When your hostname is known (e.g https://code.rhodecode.com) please set it
+ inside :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
-.. tip::
+ add into `[app:main]` section the following configuration:
+
+ .. code-block:: ini
+
+ app.base_url = https://code.rhodecode.com
- Best practice would be to create a special SSH user account with each
- users |authtoken| attached.
+
+4. Add the public key to your user account for testing.
+ First generate a new key, or use your existing one and have your public key
+ at hand.
- |RCE| will manage the user permissions based on the |authtoken| supplied.
- This would allow you to immediately revoke all SSH access by removing one
- user from your server if you needed to.
+ Go to
+ :menuselection:`My Account --> SSH Keys` and add the public key with proper description.
-See the following command line example of setting this up. These steps
-take place on the server.
+ This will generate a new entry inside our configured `authorized_keys_rhodecode` file.
-.. code-block:: bash
+ Test the connection from your local machine using the following example:
+
+ .. note::
- # On the RhodeCode Enterprise server
- # set up user and clone SSH tool
- $ sudo adduser testuser
- $ sudo su - testuser
- $ hg clone https://code.rhodecode.com/rhodecode-ssh
- $ cd rhodecode-ssh
+ In case of connection problems please set
+ `ssh.enable_debug_logging = true` inside the SSH configuration of
+ :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
+ Then add, remove your SSH key and try connecting again.
+ Debug logging will be printed to help find the problems on the server side.
- # Copy and modify the sshwrapper.ini as explained in step 4
- $ cp sshwrapper.sample.ini sshwrapper.ini
+ Test connection using the ssh command from the local machine
+
+
+ For SVN:
+
+ .. code-block:: bash
- $ cd ~
- $ mkdir .ssh
- $ touch .ssh/authorized_keys
+ SVN_SSH="ssh -i ~/.ssh/id_rsa_test_ssh" svn checkout svn+ssh://rhodecode@rc-server/repo_name
+
+ For GIT:
- # copy your ssh public key, id_rsa.pub, from your local machine
- # to the server. We’ll use it in the next step
+ .. code-block:: bash
- $ python addkey.py --user testuser --shell --key /path/to/id_rsa.pub
+ GIT_SSH_COMMAND='ssh -i ~/.ssh/id_rsa_test_ssh' git clone ssh://rhodecode@rc-server/repo_name
- # Note: testssh - user on the rhodecode instance
- $ chmod 755 sshwrapper.py
+ For Mercurial:
-Test the connection from your local machine using the following example:
+ .. code-block:: bash
-.. code-block:: bash
+ Add to hgrc:
- # Test connection using the ssh command from the local machine
- $ ssh testuser@my-server.example.com
+ [ui]
+ ssh = ssh -C -i ~/.ssh/id_rsa_test_ssh
+
+ hg clone ssh://rhodecode@rc-server/repo_name