##// 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::
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:
9 1. Include |RCE| generated `authorized_keys` file into your sshd_config.
17 10
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.
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.
24 15
25 * For |git|, see
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
16 .. code-block:: bash
35 17
36 [api]
37 host=http://localhost:10005
38 key=24a67076d69c84670132f55166ac79d1faafd660
18 # Edit sshd_config file most likely at /etc/ssh/sshd_config
19 # add or edit the AuthorizedKeysFile, and set to use custom files
39 20
40 [shell]
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
21 AuthorizedKeysFile %h/.ssh/authorized_keys %h/.ssh/authorized_keys_rhodecode
48 22
49 [vcs:hg]
50 path=/usr/bin/hg
23 This way we use a separate file for SSH access and separate one for
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]
57 path=/home/user/.ssh/authorized_keys
27 2. Enable the SSH module on instance.
58 28
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:
29 On the server where |RCE| is running executing:
63 30
64 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
71 each users |authtoken| in the :file:`authorized_keys` file.
76
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 119 .. code-block:: bash
76 120
77 $ ssh user@localhost
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
121 SVN_SSH="ssh -i ~/.ssh/id_rsa_test_ssh" svn checkout svn+ssh://rhodecode@rc-server/repo_name
87 122
88 .. tip::
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.
123 For GIT:
99 124
100 125 .. code-block:: bash
101 126
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
109 # Copy and modify the sshwrapper.ini as explained in step 4
110 $ cp sshwrapper.sample.ini sshwrapper.ini
127 GIT_SSH_COMMAND='ssh -i ~/.ssh/id_rsa_test_ssh' git clone ssh://rhodecode@rc-server/repo_name
111 128
112 $ cd ~
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:
129 For Mercurial:
125 130
126 131 .. code-block:: bash
127 132
128 # Test connection using the ssh command from the local machine
129 $ ssh testuser@my-server.example.com
133 Add to hgrc:
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