tdocumentation updates for first release - gitzone - git-based zone management tool for static and dynamic domains (HTM) git clone https://git.parazyd.org/gitzone (DIR) Log (DIR) Files (DIR) Refs --- (DIR) commit 26dfd85ca5ff5cc79744494e1fa8727cedb3102c (DIR) parent a546e75c82fde864c1a01be8129818395229a55f (HTM) Author: Jaromil <jaromil@dyne.org> Date: Thu, 31 Oct 2013 12:00:08 +0100 documentation updates for first release Diffstat: M Makefile | 3 +++ M README.org | 93 ++++++++++++++++++++++++------- 2 files changed, 75 insertions(+), 21 deletions(-) --- (DIR) diff --git a/Makefile b/Makefile t@@ -1,5 +1,8 @@ PREFIX=/usr +all: + @echo "Nothing to compile. run 'make install' as root (default prefix is /usr)" + install: mkdir -p ${PREFIX}/bin mkdir -p ${PREFIX}/libexec/gitzone (DIR) diff --git a/README.org b/README.org t@@ -4,49 +4,100 @@ #+INFOJS_OPT: view:showall ltoc:nil #+STYLE: <style>html{max-width:1000px}</style> +#+LATEX_HEADER: \usepackage{lmodern} +#+LATEX_HEADER: \usepackage{fullpage} + * About -gitzone is a git-based zone file management tool for BIND. Users can update +Gitzone is a git-based zone file management tool for BIND. Users can update their zones in a git repository then during a push the zone files are checked, updated & reloaded from git receive hooks. If there's an error in a file being pushed then the push is rejected, thus only correct files are stored on the -server. +server. Gitzone is written in Perl. + +Gitzone-shell is similar to git-shell but it restricts the user to the +zones repository and provides some additional commands for dynamic DNS +updates & SSH key management. Gitzone-shell and the Gitzone-install +scripts are written in Zsh shell script. + +#+LATEX: \pagebreak -gitzone-shell is similar to git-shell but it restricts the user to the zones -repository and provides some additional commands for dynamic DNS updates & SSH -key management. To use it the Z shell must be installed (zsh). * Installation (semi-automatic) -Gitzone comes with a relatively simple script: gitzone-install -whose usage is self-descriptive: +First install Bind9 (not covered by this documentation). + +Then install all scripts in the prefix /bin path and /libexec + + : # make install + +Once the binaries are in place, to enable gitzone for a user there is +a relatively simple script: gitzone-install. Usage synopsis: + + : # gitzone-install username id_rsa.pub - : # gitzone-install username [ id_rsa.pub ] +This script assumes that a user with 'username' (first argument) +already exists: anyone with access to this user will be in control of +gitzone, since access is managed via ssh authentication. -First argument is a user on the machine which will be the user in the git url. +Second argument is the first public ssh key which will have write +permissions to change zones (more keys can be added later). -Second argument is the first public ssh key which will have write permissions to change zones -(it is optional and can be added later) +If you intend to use the dynamic DNS feature via the gitzone-shell, +then you'd better create a specific user only for gitzone. -So first install bind9 (not covered by this documentation), -then create your user and then run the script with all the arguments in place. +Once ready, run the script with all the arguments in place. Then create /etc/bind/repos/${user}.conf and put inside: -: zone "domain.com" { -: type master; -: notify yes; -: file "/var/cache/bind/$user/domain.com"; -: allow-transfer { transfer; }; -: }; +#+BEGIN_EXAMPLE +zone "domain.com" { + type master; + notify yes; + file "/var/cache/bind/$user/domain.com"; + allow-transfer { transfer; }; +}; +#+END_EXAMPLE + +Where 'domain.com' is the first domain you are managing with +gitzone. There can be more domains and for each of them the above +configuration section must be created. + +Now clone the gitzone repository from another user that has access to +the ssh secret key configured in gitzone-install. The git url will be +composed of the hostname of the machine where is has been installed +and the username chosen: + +: git clone username@ns.myown.net:zones/username gitzone-admin + +The command above will clone the new gitzone repository into a +directory gitzone-admin. If you aren't familiar with git, this is a +good time to go study it. + +Create a file named 'domain.com' inside gitzone-admin and fill it in +as a canonical DNS zone file for bind9. Then add, commit and push: + +#+BEGIN_EXAMPLE +cd gitzone-admin; vim domain.com + (edit the zone file according to bind9 documentation) +git add domain.com +git commit -m "initial zone commit for domain.com" +git push +#+END_EXAMPLE + +If the domain.com file contains any errors, gitzone will not accept +the push and will report an error among the screen messages. + -Then restart the bind9 daemon. +If all went well, restart the bind9 daemon and you'll see that the +zone for domain.com is served by your new DNS. One can check using +nslookup. Gitzone can be installed on multiple users on the same machine, this way there can be different admins (or groups of admins) for different zones all on the same machine. -* Installation (manual) +* Installation (in close detail) - set PREFIX in Makefile and make sure the paths in the hooks are correct, then : # make install