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
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6 <!ENTITY gitgid "58">
7 <!ENTITY gituid "58">
10<sect1 id="gitserver" xreflabel="Running a Git Server">
11 <?dbhtml filename="gitserver.html"?>
13 <sect1info>
14 <date>$Date$</date>
15 </sect1info>
17 <title>Running a Git Server</title>
19 <sect2 role="package">
20 <title>Introduction</title>
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=""/>.
27 </para>
29 <bridgehead renderas="sect3">Server Dependencies</bridgehead>
31 <bridgehead renderas="sect4">Required</bridgehead>
32 <para role="required">
33 <xref linkend="git"/> and
34 <xref linkend="openssh"/>
35 </para>
37 </sect2>
39 <sect2 role="configuration">
40 <title>Setting up a Git Server</title>
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>
49 <para>
50 Configuration of the server consists of the following steps:
51 </para>
53 <sect3>
54 <title>1. Setup Users, Groups, and Permissions</title>
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>
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>
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>
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>
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>
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>
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>
96<screen role="nodump"><userinput>git config --system init.defaultBranch trunk</userinput></screen>
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>
106<screen role="root"><userinput>echo "/usr/bin/git-shell" &gt;&gt; /etc/shells</userinput></screen>
108 </sect3>
110 <sect3>
111 <title>2. Create a git repository</title>
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>
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>
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>
135 </sect3>
137 <sect3>
138 <title>3. Populate the repository from a client system</title>
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>
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>
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>
160<screen role="nodump"><userinput>cat &gt; ~/.gitconfig &lt;&lt;EOF
162 name = &lt;users-name&gt;
163 email = &lt;users-email-address&gt;
166 <para>
167 On the developer's machine, setup some files to be pushed
168 to the repository as the initial content:
169 </para>
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>
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
185git add README
186git commit -m 'Initial creation of README'
187git push --set-upstream origin trunk</userinput></screen>
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>
197<screen role="nodump"><userinput>git push</userinput></screen>
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>
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>
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>
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>
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>
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>
246 </sect3>
248 <sect3 id="gitserver-init">
249 <title>4. Configure the Server</title>
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>
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>
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>
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>
278 <indexterm zone="gitserver gitserver-init" revision="sysv">
279 <primary sortas="f-git">git</primary>
280 </indexterm>
282<screen role="root" revision="sysv"><userinput>make install-git-daemon</userinput></screen>
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>
290 <indexterm zone="gitserver gitserver-init" revision="systemd">
291 <primary sortas="f-gitserve">gitserve</primary>
292 </indexterm>
294<screen role="root" revision="systemd"><userinput>make install-git-daemon</userinput></screen>
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>
304<screen role="root"><userinput>touch /srv/git/project1.git/git-daemon-export-ok</userinput></screen>
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
319# Specify the location of the git repository
322# Directories added to whitelist
325# Add extra options which will appended to the 'git daemon'
326# command executed in the boot script
329# End /etc/sysconfig/git-daemon
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>
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>
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>
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>
391 </sect3>
393 </sect2>
Note: See TracBrowser for help on using the repository browser.