tREADME.org - gitzone - git-based zone management tool for static and dynamic domains
HTML git clone https://git.parazyd.org/gitzone
DIR Log
DIR Files
DIR Refs
---
tREADME.org (9200B)
---
1 #+TITLE: gitzone
2 #+AUTHOR: tg(x)
3 #+OPTIONS: ^:{}
4 #+INFOJS_OPT: view:showall ltoc:nil
5 #+STYLE: <style>html{max-width:1000px}</style>
6
7 #+LATEX_HEADER: \usepackage{lmodern}
8 #+LATEX_HEADER: \usepackage{fullpage}
9
10 * About
11
12 Gitzone is a git-based zone file management tool for BIND. Users can update
13 their zones in a git repository then during a push the zone files are checked,
14 updated & reloaded from git receive hooks. If there's an error in a file being
15 pushed then the push is rejected, thus only correct files are stored on the
16 server. Gitzone is written in Perl.
17
18 Gitzone-shell is similar to git-shell but it restricts the user to the
19 zones repository and provides some additional commands for dynamic DNS
20 updates & SSH key management.
21 #+LATEX: \pagebreak
22
23
24 * Installation (semi-automatic)
25
26 First install Bind9 (not covered by this documentation).
27
28 Then install all scripts in the prefix /bin path and /libexec
29
30 : # make install
31
32 Once the binaries are in place, to enable gitzone for a user there is
33 a relatively simple script: gitzone-install. Usage synopsis:
34
35 : # gitzone-install username id_rsa.pub
36
37 This script assumes that a user with 'username' (first argument)
38 already exists: anyone with access to this user will be in control of
39 gitzone, since access is managed via ssh authentication.
40
41 Second argument is the first public ssh key which will have write
42 permissions to change zones (more keys can be added later).
43
44 If you intend to use the dynamic DNS feature via the gitzone-shell,
45 then you'd better create a specific user only for gitzone.
46
47 Once ready, run the script with all the arguments in place.
48
49 Then create /etc/bind/repos/${user}.conf and put inside:
50
51 #+BEGIN_EXAMPLE
52 zone "domain.com" {
53 type master;
54 notify yes;
55 file "/var/cache/bind/$user/domain.com";
56 allow-transfer { transfer; };
57 };
58 #+END_EXAMPLE
59
60 Where 'domain.com' is the first domain you are managing with
61 gitzone. There can be more domains and for each of them the above
62 configuration section must be created.
63
64 Now clone the gitzone repository from another user that has access to
65 the ssh secret key configured in gitzone-install. The git url will be
66 composed of the hostname of the machine where is has been installed
67 and the username chosen:
68
69 : git clone username@ns.myown.net:zones/username gitzone-admin
70
71 The command above will clone the new gitzone repository into a
72 directory gitzone-admin. If you aren't familiar with git, this is a
73 good time to go study it.
74
75 Create a file named 'domain.com' inside gitzone-admin and fill it in
76 as a canonical DNS zone file for bind9. Then add, commit and push:
77
78 #+BEGIN_EXAMPLE
79 cd gitzone-admin; vim domain.com
80 (edit the zone file according to bind9 documentation)
81 git add domain.com
82 git commit -m "initial zone commit for domain.com"
83 git push
84 #+END_EXAMPLE
85
86 If the domain.com file contains any errors, gitzone will not accept
87 the push and will report an error among the screen messages.
88
89
90 If all went well, restart the bind9 daemon and you'll see that the
91 zone for domain.com is served by your new DNS. One can check using
92 nslookup.
93
94 Gitzone can be installed on multiple users on the same machine,
95 this way there can be different admins (or groups of admins)
96 for different zones all on the same machine.
97
98 * Installation (in close detail)
99
100 - set PREFIX in Makefile and make sure the paths in the hooks are correct, then
101 : # make install
102
103 - edit path settings in gitzone-shell
104
105 - create users with ssh access and set their shell to gitzone-shell
106
107 - create a zones repo for each user and set receive.denyCurrentBranch to ignore,
108 this allows pushing to a checked out repository. The checked out files are
109 used for incrementing serials and validating the zones with named-checkzone.
110 : # mkdir -p ~$user/zones
111 : # cd ~$user/zones
112 : # git init $user
113 : # cd $user
114 : # git config receive.denyCurrentBranch ignore
115 : # cd .git/hooks
116 : # ln -s /usr/libexec/gitzone/pre-receive
117 : # ln -s /usr/libexec/gitzone/post-receive
118
119 - if you want to use a repository locally add these hooks as well / instead:
120 : # ln -s /usr/libexec/gitzone/pre-commit
121 : # ln -s /usr/libexec/gitzone/post-commit
122
123 - create a .gitconfig for each user that contains user name & user email (used
124 for auto increment commits):
125 : # git config -f ~$user/.gitconfig user.name $user
126 : # git config -f ~$user/.gitconfig user.email "$user@ns.example.com"
127
128 - add ssh keys to ~$user/.ssh/authorized_keys and enable ssh key editing if desired:
129 : # touch ~$user/.ssh/authorized_keys_edit_allowed
130
131 - make sure the user's HOME directory has correct permissions:
132 : # chown -R $user:users ~$user
133
134 - edit the settings in gitzone.conf
135
136 - create a directory for each user in $zone_dir and chown them to the users, this
137 will contain a clone of the user's repository, the zone files here should be
138 included in named.conf.
139 : # cd $zone_dir
140 : # mkdir $user
141 : # chown $user:$group $user
142
143 - edit named.conf
144 - set directory in options to $zone_dir, this is needed to make relative file
145 names work in $INCLUDE:
146 : options {
147 : directory "/var/named";
148 : // ...
149 : }
150
151 - put user zone configuration in a separate file for each user and include them:
152 : include "/etc/bind/repos/user1.conf";
153 : include "/etc/bind/repos/user2.conf";
154 : include "/etc/bind/repos/user3.conf";
155
156 * Usage
157
158 ** Git repository
159
160 To make changes to the zones you need to clone the git repository, edit the
161 files, commit the changes and finally push the changes to the server. If you
162 use the auto increment feature you also need to pull after a push as the receive
163 hooks on the server make commits to the repository during a push.
164
165 #+BEGIN_EXAMPLE
166 % git clone ns.example.net:zones/$user zones
167 % # or if you're using gitzone-shell you can use any path:
168 % git clone ns.example.net:zones
169 % cd zones
170 % # edit files
171 % git add .
172 % git commit -m 'commit msg'
173 % git push origin && git pull
174 #+END_EXAMPLE
175
176 ** SSH commands
177
178 The following SSH commands are provided by gitzone-shell:
179
180 - =update-record <filename> <record>=: updates the IP address of the first matched
181 record in the given file to the SSH client's IP address.
182 : % ssh ns.example.net update-record example.net somehost IN A
183
184 - SSH key management commands, to use these do:
185 : touch .ssh/authorized_keys_edit_allowed
186 in the users' home directories.
187
188 - =list-keys=: list added ssh keys
189 : % ssh ns.example.net list-keys
190
191 - =add-key=: add a new ssh key
192 : % ssh ns.example.net add-key `cat id_rsa.pub`
193
194 or only allow one specific command:
195 : % ssh ns.example.net add-key 'command="update-record example.net somehost IN A"' `cat id_rsa.pub`
196
197 - =del-key=: delete an ssh key from the config
198 : % ssh ns.example.net del-key user@somewhere
199
200 ** Dynamic DNS
201
202 In order to do automatic dynamic DNS updates, create an SSH key without a
203 password and use the add-key command to add it with a command= parameter which
204 has an update-record command in it, see the example in the previous
205 section. This way the host doing the updates does not have access to the git
206 repository as it is restricted to the specified command only. Then all you have to do to
207 update your IP is:
208 : % ssh ns.example.net
209
210 Run this command whenever the IP changes or the interface comes up.
211
212 *** Debian, Ubuntu
213
214 On Debian-like systems you can use a post-up command in =/etc/network/interfaces=.
215
216 *** Gentoo
217
218 On Gentoo you can put a postup() function in =/etc/conf.d/net=.
219
220 ** Zone files
221
222 There are a few keywords you can use in the zone files:
223
224 - ;AUTO_INCREMENT after a serial number to automatically increment it during
225 a push. If the number is 10 digits and starts with 20 it's treated as a date.
226 e.g.:
227 : example.net. IN SOA ns1.example.net. hostmaster.example.net. (
228 : 2011013101 ;AUTO_INCREMENT
229 : 1d 2h 4w 2d )
230
231 - $INCLUDE can be used to include other files from the repository, the file
232 names should be prefixed with the user name
233
234 - ;INCLUDED_BY on the first line of a file indicates what other files include
235 this file. When this file is committed & pushed all the other files listed
236 after ;INCLUDED_BY are reloaded as well.
237
238 E.g. if you have the following files in the repository then a change in
239 example-common would result in the reload of both example.net & example.org:
240
241 - example.net:
242 : ...
243 : $INCLUDE username/example-common example.net.
244
245 - example.org:
246 : ...
247 : $INCLUDE username/example-common example.org.
248
249 - example-common:
250 : ;INCLUDED_BY example.net example.org
251 : ...
252
253 * Acknowledgements
254
255 Gitzone is copyright (C) 2013-2019 by Dyne.org foundation, Amsterdam
256
257 Designed and written by tg(x)
258
259 Maintained and documented by Denis Roio and Ivan J.
260
261 With contributions by Zephaniah Loss-Cutler-Hull
262
263 Gitzone is Licensed under the terms of the Affero GNU Public License
264 as published by the Free Software Foundation; either version 3 of the
265 License, or (at your option) any later version.
266
267 Unless required by applicable law or agreed to in writing, software
268 distributed under the License is distributed on an "AS IS" BASIS,
269 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
270 implied. See [the License](LICENSE.txt).