source: general/prog/gitserver.xml@ 5f729f8

11.2 plabs/python-mods trunk xry111/soup3
Last change on this file since 5f729f8 was 5f729f8, checked in by Douglas R. Reno <renodr@…>, 4 months ago

Various typo fixes

  • Property mode set to 100644
File size: 14.4 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6 <!ENTITY gitgid "58">
7 <!ENTITY gituid "58">
8]>
9
10<sect1 id="gitserver" xreflabel="Running a Git Server">
11 <?dbhtml filename="gitserver.html"?>
12
13 <sect1info>
14 <date>$Date$</date>
15 </sect1info>
16
17 <title>Running a Git Server</title>
18
19 <sect2 role="package">
20 <title>Introduction</title>
21
22 <para>
23 This section will describe how to set up, administer and secure a
24 <application>git</application> server. <application>Git</application>
25 has many options available. For more detailed documentation see
26 <ulink url="https://git-scm.com/book/en/v2"/>.
27 </para>
28
29 <bridgehead renderas="sect3">Server Dependencies</bridgehead>
30
31 <bridgehead renderas="sect4">Required</bridgehead>
32 <para role="required">
33 <xref linkend="git"/> and
34 <xref linkend="openssh"/>
35 </para>
36
37 </sect2>
38
39 <sect2 role="configuration">
40 <title>Setting up a Git Server</title>
41
42 <para>
43 The following instructions will install a
44 <application>git</application> server. It will be set
45 up to use <application>OpenSSH</application> as the secure
46 remote access method.
47 </para>
48
49 <para>
50 Configuration of the server consists of the following steps:
51 </para>
52
53 <sect3>
54 <title>1. Setup Users, Groups, and Permissions</title>
55
56 <para>
57 You will need to be user <systemitem class='username'>root</systemitem>
58 for the initial portion of configuration. Create the <systemitem
59 class="username">git</systemitem> user and group and set and unusable
60 password hash with the following commands:
61 </para>
62
63<screen role="root"><userinput>groupadd -g &gitgid; git &amp;&amp;
64useradd -c "git Owner" -d /home/git -m -g git -s /usr/bin/git-shell -u &gituid; git &amp;&amp;
65sed -i '/^git:/s/^git:[^:]:/git:NP:/' /etc/shadow</userinput></screen>
66
67 <para>
68 Putting in an unusable password hash (replacing the <literal>!</literal>
69 by <literal>NP</literal>) unlocks the account but it cannot be used
70 to login via password authentication. That is required by
71 <application>sshd</application> to work properly.
72 Next, create some files and directories in the home directory of the git user
73 allowing access to the git repository using ssh keys.
74 </para>
75
76<screen role="root"><userinput>install -o git -g git -dm0700 /home/git/.ssh &amp;&amp;
77install -o git -g git -m0600 /dev/null /home/git/.ssh/authorized_keys</userinput></screen>
78
79 <para>
80 For any developer who should have access to the repository
81 add his/her public ssh key to <filename>/home/git/.ssh/authorized_keys</filename>.
82 First, prepend some options to prevent users from using the
83 connection to git for port forwarding to other machines
84 the git server might reach.
85 </para>
86
87<screen role="nodump"><userinput>echo -n "no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty " >> /home/git/.ssh/authorized_keys &amp;&amp;
88cat &lt;user-ssh-key&gt; &gt;&gt; /home/git/.ssh/authorized_keys</userinput></screen>
89
90 <para>
91 It is also useful to set the default name of the initial branch
92 of new repositories by modifying the git configuration. As the
93 <systemitem class='username'>root</systemitem> user, run:
94 </para>
95
96<screen role="nodump"><userinput>git config --system init.defaultBranch trunk</userinput></screen>
97
98 <para>
99 Finally add the <filename>/usr/bin/git-shell</filename> entry to
100 the <filename>/etc/shells</filename> configuration file. This shell
101 has been set in the <systemitem class='username'>git</systemitem>
102 user profile and is to make sure that only git related actions
103 can be executed:
104 </para>
105
106<screen role="root"><userinput>echo "/usr/bin/git-shell" &gt;&gt; /etc/shells</userinput></screen>
107
108 </sect3>
109
110 <sect3>
111 <title>2. Create a git repository</title>
112
113 <para>
114 The repository can be anywhere on the filesystem. It is
115 important that the git user has read/write access to that
116 location. We use <filename class="directory">/srv/git</filename>
117 as base directory. Create a new <application>git</application>
118 repository with the following commands (as the
119 <systemitem class="username">root</systemitem> user):
120 </para>
121
122 <note>
123 <para>
124 In all the instructions below, we use <emphasis>project1</emphasis>
125 as an example repository name. You should name your repository
126 as a short descriptive name for your specific project.
127 </para>
128 </note>
129
130<screen role="root"><userinput>install -o git -g git -m755 -d /srv/git/project1.git &amp;&amp;
131cd /srv/git/project1.git &amp;&amp;
132git init --bare &amp;&amp;
133chown -R git:git .</userinput></screen>
134
135 </sect3>
136
137 <sect3>
138 <title>3. Populate the repository from a client system</title>
139
140 <note>
141 <para>
142 All the instructions in this section and the next should
143 be done on a user system, not the server system.
144 </para>
145 </note>
146
147 <para>
148 Now that the repository is created, it can be used by the
149 developers to put some files into it. Once the ssh key of
150 the user is imported to git's <filename>authorized_keys</filename>
151 file, the user can interact with the repository.
152 </para>
153
154 <para>
155 A minimal configuration should be available on the developer's
156 system specifying its user name and the email address.
157 Create this minimal config file on client side:
158 </para>
159
160<screen role="nodump"><userinput>cat &gt; ~/.gitconfig &lt;&lt;EOF
161[user]
162 name = &lt;users-name&gt;
163 email = &lt;users-email-address&gt;
164EOF</userinput></screen>
165
166 <para>
167 On the developer's machine, setup some files to be pushed
168 to the repository as the initial content:
169 </para>
170
171 <note>
172 <para>
173 The <emphasis>gitserver</emphasis> term used below
174 should be the host name (or ip address) of the git server.
175 </para>
176 </note>
177
178<screen role="nodump"><userinput>mkdir myproject
179cd myproject
180git init --initial-branch=trunk
181git remote add origin git@gitserver:/srv/git/project1.git
182cat &gt;README &lt;&lt;EOF
183This is the README file
184EOF
185git add README
186git commit -m 'Initial creation of README'
187git push --set-upstream origin trunk</userinput></screen>
188
189 <para>The initial content is now pushed to the server and
190 is available for other users. On the current machine, the
191 argument <literal>--set-upstream origin trunk</literal> is
192 now no longer required as the local repository is now
193 connected to the remote repository. Subsequent pushes
194 can be performed as
195 </para>
196
197<screen role="nodump"><userinput>git push</userinput></screen>
198
199 <para>
200 Other developers can now clone the repository and do
201 modifications to the content (as long as their ssh keys
202 has been installed):
203 </para>
204
205<screen role="nodump"><userinput>git clone git@gitserver:/srv/git/project1.git
206cd project1
207vi README
208git commit -am 'Fix for README file'
209git push</userinput></screen>
210
211 <note>
212 <para>
213 This is a very basic server setup based on
214 <application>OpenSSH</application> access. All developers are using
215 the <systemitem class="username">git</systemitem> user to perform
216 actions on the repository and the changes users are committing can be
217 distinguished as the local user name (see
218 <filename>~/.gitconfig</filename>) is recorded in the
219 changesets.
220 </para>
221 </note>
222
223 <para>
224 Access is restricted by the public keys added to git's
225 <filename>authorized_keys</filename> file and there is no
226 option for the public to export/clone the repository. To
227 enable this, continue with step 4 to set up the git server
228 for public read-only access.
229 </para>
230
231 <para>
232 In the URL used to clone the project, the absolute path (here
233 <filename>/srv/git/project1.git</filename>) has to be specified
234 as the repository is not in git's home directory but in
235 <filename class="directory">/srv/git</filename>. To get rid of the
236 need to expose the structure of the server installation, a symlink
237 can be added in git's home directory for each project like this:
238 </para>
239<screen role="nodump"><userinput>ln -svf /srv/git/project1.git /home/git/</userinput></screen>
240
241 <para>
242 Now, the repository can be cloned using
243 </para>
244<screen role="nodump"><userinput>git clone git@gitserver:project1.git</userinput></screen>
245
246 </sect3>
247
248 <sect3 id="gitserver-init">
249 <title>4. Configure the Server</title>
250
251 <para>
252 The setup described above makes a repository available for
253 authenticated users (via providing the ssh public key file).
254 There is also a simple way to publish the
255 repository to unauthenticated users &mdash; of course without write
256 access.
257 </para>
258
259 <para>
260 The combination of access via ssh (for authenticated users) and
261 the export of repositories to unauthenticated users via the
262 daemon is in most cases enough for a development site.
263 </para>
264
265 <note>
266 <para>
267 The daemon will be reachable at port <literal>9418</literal>
268 by default. Make sure that your firewall setup allows
269 access to that port.
270 </para>
271 </note>
272
273 <para revision="sysv">
274 To start the server at boot time, install the git-daemon
275 bootscript included in the <xref linkend="bootscripts"/> package:
276 </para>
277
278 <indexterm zone="gitserver gitserver-init" revision="sysv">
279 <primary sortas="f-git">git</primary>
280 </indexterm>
281
282<screen role="root" revision="sysv"><userinput>make install-git-daemon</userinput></screen>
283
284 <para revision="systemd">
285 To start the server at boot time, install the
286 <filename>git-daemon.service</filename> unit from the
287 <xref linkend="systemd-units"/> package:
288 </para>
289
290 <indexterm zone="gitserver gitserver-init" revision="systemd">
291 <primary sortas="f-gitserve">gitserve</primary>
292 </indexterm>
293
294<screen role="root" revision="systemd"><userinput>make install-git-daemon</userinput></screen>
295
296 <para>
297 In order to allow <application>git</application> to export a
298 repository, a file named <filename>git-daemon-export-ok</filename>
299 is required in each repository directory on the server. The
300 file needs no content, just its existence enables, its absence
301 disables the export of that repository.
302 </para>
303
304<screen role="root"><userinput>touch /srv/git/project1.git/git-daemon-export-ok</userinput></screen>
305
306 <para revision="sysv">
307 The script to start the git daemon uses some default values
308 internally. Most important is the path to the repository
309 directory which is set to <filename class="directory">/srv/git</filename>.
310 In case you have for whatever reason created the repository in a
311 different location, you'll need to tell the boot script where the
312 repository is to be found. This can be achieved by creating a
313 configuration file named <filename>/etc/sysconfig/git-daemon</filename>.
314 This configuration file will be imported if it exists, meaning it is
315 optional. The file can look like:</para>
316<screen revision="sysv">
317# Begin /etc/sysconfig/git-daemon
318
319# Specify the location of the git repository
320GIT_BASE_DIR="/srv/git/"
321
322# Directories added to whitelist
323DFT_REPO_DIR="$GIT_BASE_DIR"
324
325# Add extra options which will appended to the 'git daemon'
326# command executed in the boot script
327GIT_DAEMON_OPTS=""
328
329# End /etc/sysconfig/git-daemon
330</screen>
331 <para revision="systemd">
332 Along with the <filename>git-daemon.service</filename> unit, a
333 configuration file named <filename>/etc/default/git-daemon</filename>
334 has been installed. Review this configuration file to match your
335 needs.
336 </para>
337
338 <para>
339 There are only three options to set in the configuration file:
340 <itemizedlist>
341 <listitem>
342 <para>
343 GIT_BASE_DIR=&lt;dirname&gt;
344 </para>
345 <para>Specify the location of the git repositories.
346 Relative paths used when accessing the daemon will
347 translated relative to this directory.
348 </para>
349 </listitem>
350 <listitem>
351 <para>
352 DFT_REPO_DIR=&lt;dirname&gt;
353 </para>
354 <para>This directory is added to the white list of allowed
355 directories. This variable can hold multiple directory
356 names but is usually set equal to <literal>GIT_BASE_DIR</literal>.
357 </para>
358 </listitem>
359 <listitem>
360 <para>
361 GIT_DAEMON_OPTS=&lt;options&gt;
362 </para>
363 <para>
364 In case special options to the <command>git daemon</command>
365 command are needed, they have to be specified in this setting.
366 One example might be to adjust the port number where daemon is
367 listening. In this case, add <literal>--port=&lt;port
368 number&gt;</literal> to this variable. For more information
369 about which options can be set, take a look at the output of
370 <command>git daemon --help</command>.
371 </para>
372 </listitem>
373 </itemizedlist>
374 </para>
375
376 <para>
377 After starting the daemon, unauthenticated users can clone exported
378 repositories by using
379 </para>
380<screen role="nodump"><userinput>git clone git://gitserver/project1.git</userinput></screen>
381
382 <para>
383 As the base directory is <filename class="directory">/srv/git</filename>
384 by default (or set to a custom value in the configuration),
385 <application>git</application> interprets the incoming path
386 (/project1.git) relative to that base directory so that the repository
387 in <filename class="directory">/srv/git/project1.git</filename> is
388 served.
389 </para>
390
391 </sect3>
392
393 </sect2>
394
395</sect1>
Note: See TracBrowser for help on using the repository browser.