source: general/prog/gitserver.xml@ 1e72aaad

10.1 11.0 11.1 11.2 lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since 1e72aaad was 1e72aaad, checked in by Thomas Trepl <thomas@…>, 2 years ago

Add a sed to set invalid password hash; set default branch name system wide

git-svn-id: svn:// af4574ff-66df-0310-9fd7-8a98e5e911e0

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