##// 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 .. _ssh-connection:
1 .. _ssh-connection:
2
2
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
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
16 .. code-block:: bash
14 the |RCE| instance.
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.
23 This way we use a separate file for SSH access and separate one for
19 * *API key*: From the |RCE|, go to
24 SSH access to |RCE| repositories.
20 :menuselection:`username --> My Account --> Auth Tokens`
25
21 * *Configuration file*: Identify the configuration file for that instance,
26
22 the default is :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
27 2. Enable the SSH module on instance.
23 * Identify which |git| and |hg| packages your |RCM| instance is using.
24
28
25 * For |git|, see
29 On the server where |RCE| is running executing:
26 :menuselection:`Admin --> Settings --> System Info`
30
27 * For |hg|, use the ``which hg`` command.
31 .. code-block:: bash
28
32
29 2. Clone the |RC| SSH script,
33 rccontrol enable-module ssh {instance-id}
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
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]
38 .. code-block:: ini
37 host=http://localhost:10005
38 key=24a67076d69c84670132f55166ac79d1faafd660
39
39
40 [shell]
40 ############################################################
41 shell=/bin/bash -l
41 ### SSH Support Settings ###
42 ############################################################
42
43
43 [vcs]
44 ## Defines if a custom authorized_keys file should be created and written on
44 root=/path/to/repos/
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]
50 ## Options for ssh, default is `no-pty,no-port-forwarding,no-X11-forwarding,no-agent-forwarding`
47 config=/home/user/.rccontrol/enterprise-3/rhodecode.ini
51 # ssh.authorized_keys_ssh_opts =
48
49 [vcs:hg]
50 path=/usr/bin/hg
51
52
52 # should be a base dir for all git binaries, i.e. not ../bin/git
53 ## Path to the authrozied_keys file where the generate entries are placed.
53 [vcs:git]
54 ## It is possible to have multiple key files specified in `sshd_config` e.g.
54 path=/usr/bin
55 ## AuthorizedKeysFile %h/.ssh/authorized_keys %h/.ssh/authorized_keys_rhodecode
55
56 ssh.authorized_keys_file_path = ~/.ssh/authorized_keys_rhodecode
56 [keys]
57 path=/home/user/.ssh/authorized_keys
58
57
59 5. Add the public key to your |RCE| instance server using the
58 ## Command to execute the SSH wrapper. The binary is available in the
60 :file:`addkey.py` script. This script automatically creates
59 ## rhodecode installation directory.
61 the :file:`authorized_keys` file which was specified in your
60 ## e.g ~/.rccontrol/community-1/profile/bin/rc-ssh-wrapper
62 :file:`sshwrapper.ini` configuration. Use the following example:
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
66 ## Enables logging, and detailed output send back to the client during SSH
67
67 ## operations. Usefull for debugging, shouldn't be used in production.
68 .. important::
68 ssh.enable_debug_logging = false
69
69
70 To give SSH access to all users, you will need to maintain
70 ## Paths to binary executable, by default they are the names, but we can
71 each users |authtoken| in the :file:`authorized_keys` file.
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
77 3. Set base_url for instance to enable proper event handling (Optional):
78 Enter passphrase for key '/home/username/.ssh/id_rsa':
79
78
80 If you need to manually configure the ``authorized_keys`` file,
79 If you wish to have integrations working correctly via SSH please configure
81 add a line for each key using the following example:
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",
85 When your hostname is known (e.g https://code.rhodecode.com) please set it
86 no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-rsa yourpublickey
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
94
91 users |authtoken| attached.
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.
99 Go to
94 This would allow you to immediately revoke all SSH access by removing one
100 :menuselection:`My Account --> SSH Keys` and add the public key with proper description.
95 user from your server if you needed to.
96
101
97 See the following command line example of setting this up. These steps
102 This will generate a new entry inside our configured `authorized_keys_rhodecode` file.
98 take place on the server.
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
108 In case of connection problems please set
103 # set up user and clone SSH tool
109 `ssh.enable_debug_logging = true` inside the SSH configuration of
104 $ sudo adduser testuser
110 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
105 $ sudo su - testuser
111 Then add, remove your SSH key and try connecting again.
106 $ hg clone https://code.rhodecode.com/rhodecode-ssh
112 Debug logging will be printed to help find the problems on the server side.
107 $ cd rhodecode-ssh
108
113
109 # Copy and modify the sshwrapper.ini as explained in step 4
114 Test connection using the ssh command from the local machine
110 $ cp sshwrapper.sample.ini sshwrapper.ini
115
116
117 For SVN:
118
119 .. code-block:: bash
111
120
112 $ cd ~
121 SVN_SSH="ssh -i ~/.ssh/id_rsa_test_ssh" svn checkout svn+ssh://rhodecode@rc-server/repo_name
113 $ mkdir .ssh
122
114 $ touch .ssh/authorized_keys
123 For GIT:
115
124
116 # copy your ssh public key, id_rsa.pub, from your local machine
125 .. code-block:: bash
117 # to the server. We’ll use it in the next step
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
129 For Mercurial:
122 $ chmod 755 sshwrapper.py
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
135 [ui]
129 $ ssh testuser@my-server.example.com
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