##// END OF EJS Templates
u » ewong » rhodecode-enterprise-ce-fork
RSS

Fork of rhodecode-enterprise-ce

docs: update SSH documentation
marcink -
r2190:2920aaa0 default
parent child Browse files
Show More
Show file before | Show file after | Hide comments
@@ -1,129 +1,138 b''
1 1 .. _ssh-connection:
2 2
3 3 SSH Connection
4 4 --------------
5 5
6 If you wish to connect to your Git or Mercurial |repos| using SSH, use the
6 If you wish to connect to your |repos| using SSH protocol, use the
7 7 following instructions.
8 8
9 .. note::
9 1. Include |RCE| generated `authorized_keys` file into your sshd_config.
10 10
11 SSH access with full |RCE| permissions will require an Admin |authtoken|.
11 By default a file `authorized_keys_rhodecode` is created containing
12 configuration and all allowed user connection keys are stored inside.
13 On each change of stored keys inside |RCE| this file is updated with
14 proper data.
12 15
13 You need to install the |RC| SSH tool on the server which is running
14 the |RCE| instance.
16 .. code-block:: bash
15 17
16 1. Gather the following information about the instance you wish to connect to:
18 # Edit sshd_config file most likely at /etc/ssh/sshd_config
19 # add or edit the AuthorizedKeysFile, and set to use custom files
20
21 AuthorizedKeysFile %h/.ssh/authorized_keys %h/.ssh/authorized_keys_rhodecode
17 22
18 * *Hostname*: Use the ``rccontrol status`` command to view instance details.
19 * *API key*: From the |RCE|, go to
20 :menuselection:`username --> My Account --> Auth Tokens`
21 * *Configuration file*: Identify the configuration file for that instance,
22 the default is :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
23 * Identify which |git| and |hg| packages your |RCM| instance is using.
23 This way we use a separate file for SSH access and separate one for
24 SSH access to |RCE| repositories.
25
26
27 2. Enable the SSH module on instance.
24 28
25 * For |git|, see
26 :menuselection:`Admin --> Settings --> System Info`
27 * For |hg|, use the ``which hg`` command.
29 On the server where |RCE| is running executing:
30
31 .. code-block:: bash
28 32
29 2. Clone the |RC| SSH script,
30 ``hg clone https://code.rhodecode.com/rhodecode-ssh``
31 3. Copy the ``sshwrapper.sample.ini``, and save it as ``sshwrapper.ini``
32 4. Configure the :file:`sshwrapper.ini` file using the following example:
33 rccontrol enable-module ssh {instance-id}
33 34
34 .. code-block:: ini
35 This will add the following configuration into :file:`rhodecode.ini`.
36 This also can be done manually:
35 37
36 [api]
37 host=http://localhost:10005
38 key=24a67076d69c84670132f55166ac79d1faafd660
38 .. code-block:: ini
39 39
40 [shell]
41 shell=/bin/bash -l
40 ############################################################
41 ### SSH Support Settings ###
42 ############################################################
42 43
43 [vcs]
44 root=/path/to/repos/
44 ## Defines if a custom authorized_keys file should be created and written on
45 ## any change user ssh keys. Setting this to false also disables posibility
46 ## of adding SSH keys by users from web interface. Super admins can still
47 ## manage SSH Keys.
48 ssh.generate_authorized_keyfile = true
45 49
46 [rhodecode]
47 config=/home/user/.rccontrol/enterprise-3/rhodecode.ini
48
49 [vcs:hg]
50 path=/usr/bin/hg
50 ## Options for ssh, default is `no-pty,no-port-forwarding,no-X11-forwarding,no-agent-forwarding`
51 # ssh.authorized_keys_ssh_opts =
51 52
52 # should be a base dir for all git binaries, i.e. not ../bin/git
53 [vcs:git]
54 path=/usr/bin
55
56 [keys]
57 path=/home/user/.ssh/authorized_keys
53 ## Path to the authrozied_keys file where the generate entries are placed.
54 ## It is possible to have multiple key files specified in `sshd_config` e.g.
55 ## AuthorizedKeysFile %h/.ssh/authorized_keys %h/.ssh/authorized_keys_rhodecode
56 ssh.authorized_keys_file_path = ~/.ssh/authorized_keys_rhodecode
58 57
59 5. Add the public key to your |RCE| instance server using the
60 :file:`addkey.py` script. This script automatically creates
61 the :file:`authorized_keys` file which was specified in your
62 :file:`sshwrapper.ini` configuration. Use the following example:
58 ## Command to execute the SSH wrapper. The binary is available in the
59 ## rhodecode installation directory.
60 ## e.g ~/.rccontrol/community-1/profile/bin/rc-ssh-wrapper
61 ssh.wrapper_cmd = ~/.rccontrol/community-1/rc-ssh-wrapper
63 62
64 .. code-block:: bash
63 ## Allow shell when executing the ssh-wrapper command
64 ssh.wrapper_cmd_allow_shell = false
65 65
66 $ ./addkey.py --user username --shell --key /home/username/.ssh/id_rsa.pub
67
68 .. important::
66 ## Enables logging, and detailed output send back to the client during SSH
67 ## operations. Usefull for debugging, shouldn't be used in production.
68 ssh.enable_debug_logging = false
69 69
70 To give SSH access to all users, you will need to maintain
71 each users |authtoken| in the :file:`authorized_keys` file.
70 ## Paths to binary executable, by default they are the names, but we can
71 ## override them if we want to use a custom one
72 ssh.executable.hg = ~/.rccontrol/vcsserver-1/profile/bin/hg
73 ssh.executable.git = ~/.rccontrol/vcsserver-1/profile/bin/git
74 ssh.executable.svn = ~/.rccontrol/vcsserver-1/profile/bin/svnserve
72 75
73 6. Connect to your server using SSH from your local machine.
74
75 .. code-block:: bash
76 76
77 $ ssh user@localhost
78 Enter passphrase for key '/home/username/.ssh/id_rsa':
77 3. Set base_url for instance to enable proper event handling (Optional):
79 78
80 If you need to manually configure the ``authorized_keys`` file,
81 add a line for each key using the following example:
79 If you wish to have integrations working correctly via SSH please configure
80 The Application base_url.
82 81
83 .. code-block:: vim
82 Use the ``rccontrol status`` command to view instance details.
83 Hostname is required for the integration to properly set the instance URL.
84 84
85 command="/home/user/.rhodecode-ssh/sshwrapper.py --user username --shell",
86 no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-rsa yourpublickey
85 When your hostname is known (e.g https://code.rhodecode.com) please set it
86 inside :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
87 87
88 .. tip::
88 add into `[app:main]` section the following configuration:
89
90 .. code-block:: ini
91
92 app.base_url = https://code.rhodecode.com
89 93
90 Best practice would be to create a special SSH user account with each
91 users |authtoken| attached.
94
95 4. Add the public key to your user account for testing.
96 First generate a new key, or use your existing one and have your public key
97 at hand.
92 98
93 |RCE| will manage the user permissions based on the |authtoken| supplied.
94 This would allow you to immediately revoke all SSH access by removing one
95 user from your server if you needed to.
99 Go to
100 :menuselection:`My Account --> SSH Keys` and add the public key with proper description.
96 101
97 See the following command line example of setting this up. These steps
98 take place on the server.
102 This will generate a new entry inside our configured `authorized_keys_rhodecode` file.
99 103
100 .. code-block:: bash
104 Test the connection from your local machine using the following example:
105
106 .. note::
101 107
102 # On the RhodeCode Enterprise server
103 # set up user and clone SSH tool
104 $ sudo adduser testuser
105 $ sudo su - testuser
106 $ hg clone https://code.rhodecode.com/rhodecode-ssh
107 $ cd rhodecode-ssh
108 In case of connection problems please set
109 `ssh.enable_debug_logging = true` inside the SSH configuration of
110 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
111 Then add, remove your SSH key and try connecting again.
112 Debug logging will be printed to help find the problems on the server side.
108 113
109 # Copy and modify the sshwrapper.ini as explained in step 4
110 $ cp sshwrapper.sample.ini sshwrapper.ini
114 Test connection using the ssh command from the local machine
115
116
117 For SVN:
118
119 .. code-block:: bash
111 120
112 $ cd ~
113 $ mkdir .ssh
114 $ touch .ssh/authorized_keys
121 SVN_SSH="ssh -i ~/.ssh/id_rsa_test_ssh" svn checkout svn+ssh://rhodecode@rc-server/repo_name
122
123 For GIT:
115 124
116 # copy your ssh public key, id_rsa.pub, from your local machine
117 # to the server. We’ll use it in the next step
125 .. code-block:: bash
118 126
119 $ python addkey.py --user testuser --shell --key /path/to/id_rsa.pub
127 GIT_SSH_COMMAND='ssh -i ~/.ssh/id_rsa_test_ssh' git clone ssh://rhodecode@rc-server/repo_name
120 128
121 # Note: testssh - user on the rhodecode instance
122 $ chmod 755 sshwrapper.py
129 For Mercurial:
123 130
124 Test the connection from your local machine using the following example:
131 .. code-block:: bash
125 132
126 .. code-block:: bash
133 Add to hgrc:
127 134
128 # Test connection using the ssh command from the local machine
129 $ ssh testuser@my-server.example.com
135 [ui]
136 ssh = ssh -C -i ~/.ssh/id_rsa_test_ssh
137
138 hg clone ssh://rhodecode@rc-server/repo_name
General Comments 0
You need to be logged in to leave comments. Login now