##// 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
@@ -3,127 +3,136 b''
3 SSH Connection
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 following instructions.
7 following instructions.
8
8
9 .. note::
9 1. Include |RCE| generated `authorized_keys` file into your sshd_config.
10
11 SSH access with full |RCE| permissions will require an Admin |authtoken|.
12
13 You need to install the |RC| SSH tool on the server which is running
14 the |RCE| instance.
15
16 1. Gather the following information about the instance you wish to connect to:
17
10
18 * *Hostname*: Use the ``rccontrol status`` command to view instance details.
11 By default a file `authorized_keys_rhodecode` is created containing
19 * *API key*: From the |RCE|, go to
12 configuration and all allowed user connection keys are stored inside.
20 :menuselection:`username --> My Account --> Auth Tokens`
13 On each change of stored keys inside |RCE| this file is updated with
21 * *Configuration file*: Identify the configuration file for that instance,
14 proper data.
22 the default is :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
23 * Identify which |git| and |hg| packages your |RCM| instance is using.
24
15
25 * For |git|, see
16 .. code-block:: bash
26 :menuselection:`Admin --> Settings --> System Info`
27 * For |hg|, use the ``which hg`` command.
28
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
34 .. code-block:: ini
35
17
36 [api]
18 # Edit sshd_config file most likely at /etc/ssh/sshd_config
37 host=http://localhost:10005
19 # add or edit the AuthorizedKeysFile, and set to use custom files
38 key=24a67076d69c84670132f55166ac79d1faafd660
39
20
40 [shell]
21 AuthorizedKeysFile %h/.ssh/authorized_keys %h/.ssh/authorized_keys_rhodecode
41 shell=/bin/bash -l
42
43 [vcs]
44 root=/path/to/repos/
45
46 [rhodecode]
47 config=/home/user/.rccontrol/enterprise-3/rhodecode.ini
48
22
49 [vcs:hg]
23 This way we use a separate file for SSH access and separate one for
50 path=/usr/bin/hg
24 SSH access to |RCE| repositories.
51
25
52 # should be a base dir for all git binaries, i.e. not ../bin/git
53 [vcs:git]
54 path=/usr/bin
55
26
56 [keys]
27 2. Enable the SSH module on instance.
57 path=/home/user/.ssh/authorized_keys
58
28
59 5. Add the public key to your |RCE| instance server using the
29 On the server where |RCE| is running executing:
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:
63
30
64 .. code-block:: bash
31 .. code-block:: bash
65
32
66 $ ./addkey.py --user username --shell --key /home/username/.ssh/id_rsa.pub
33 rccontrol enable-module ssh {instance-id}
34
35 This will add the following configuration into :file:`rhodecode.ini`.
36 This also can be done manually:
37
38 .. code-block:: ini
39
40 ############################################################
41 ### SSH Support Settings ###
42 ############################################################
43
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
49
50 ## Options for ssh, default is `no-pty,no-port-forwarding,no-X11-forwarding,no-agent-forwarding`
51 # ssh.authorized_keys_ssh_opts =
67
52
68 .. important::
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
57
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
62
63 ## Allow shell when executing the ssh-wrapper command
64 ssh.wrapper_cmd_allow_shell = false
65
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
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
69
75
70 To give SSH access to all users, you will need to maintain
76
71 each users |authtoken| in the :file:`authorized_keys` file.
77 3. Set base_url for instance to enable proper event handling (Optional):
78
79 If you wish to have integrations working correctly via SSH please configure
80 The Application base_url.
81
82 Use the ``rccontrol status`` command to view instance details.
83 Hostname is required for the integration to properly set the instance URL.
84
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
88 add into `[app:main]` section the following configuration:
89
90 .. code-block:: ini
91
92 app.base_url = https://code.rhodecode.com
93
72
94
73 6. Connect to your server using SSH from your local machine.
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.
98
99 Go to
100 :menuselection:`My Account --> SSH Keys` and add the public key with proper description.
101
102 This will generate a new entry inside our configured `authorized_keys_rhodecode` file.
103
104 Test the connection from your local machine using the following example:
105
106 .. note::
107
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.
113
114 Test connection using the ssh command from the local machine
115
116
117 For SVN:
74
118
75 .. code-block:: bash
119 .. code-block:: bash
76
120
77 $ ssh user@localhost
121 SVN_SSH="ssh -i ~/.ssh/id_rsa_test_ssh" svn checkout svn+ssh://rhodecode@rc-server/repo_name
78 Enter passphrase for key '/home/username/.ssh/id_rsa':
79
80 If you need to manually configure the ``authorized_keys`` file,
81 add a line for each key using the following example:
82
83 .. code-block:: vim
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
87
122
88 .. tip::
123 For GIT:
89
90 Best practice would be to create a special SSH user account with each
91 users |authtoken| attached.
92
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.
96
97 See the following command line example of setting this up. These steps
98 take place on the server.
99
124
100 .. code-block:: bash
125 .. code-block:: bash
101
126
102 # On the RhodeCode Enterprise server
127 GIT_SSH_COMMAND='ssh -i ~/.ssh/id_rsa_test_ssh' git clone ssh://rhodecode@rc-server/repo_name
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
109 # Copy and modify the sshwrapper.ini as explained in step 4
110 $ cp sshwrapper.sample.ini sshwrapper.ini
111
128
112 $ cd ~
129 For Mercurial:
113 $ mkdir .ssh
114 $ touch .ssh/authorized_keys
115
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
118
119 $ python addkey.py --user testuser --shell --key /path/to/id_rsa.pub
120
121 # Note: testssh - user on the rhodecode instance
122 $ chmod 755 sshwrapper.py
123
124 Test the connection from your local machine using the following example:
125
130
126 .. code-block:: bash
131 .. code-block:: bash
127
132
128 # Test connection using the ssh command from the local machine
133 Add to hgrc:
129 $ ssh testuser@my-server.example.com
134
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