README.rst

   1 **********
   2 ssh-dyndns
   3 **********
   4 Update DNS records by simply SSH'ing into a server.
   5
   6 The idea is to create a separate "dyndns" user on the DNS server.
   7 It gets the ``ssh-dyndns`` script as login shell, so that no other programs
   8 may be executed.
   9 SSH provides secure, password-less key-based authentication.
  10
  11 Upon login, the remote IP is used to create/update a tinydns file with the
  12 DNS record for a hostname given by the SSH client.
  13 In addition to the IP record, a TXT record with the update time will be added.
  14
  15 tinydns is part of the dbjdns/dbndns package.
  16
  17
  18 =====
  19 Setup
  20 =====
  21
  22 Server
  23 ======
  24 1. Clone ssh-dyndns into a sensible location, e.g. ``/usr/local/src/ssh-dyndns``::
  25
  26     $ cd /usr/local/src/ && git clone git://git.cweiske.de/ssh-dyndns.git
  27
  28 2. Create a user with ``ssh-dyndns`` as login shell::
  29
  30     $ useradd -g nogroup -m -N -s /usr/local/src/ssh-dyndns/ssh-dyndns dyndns
  31
  32 3. Prepare password-less ssh keys for the dyndns user::
  33
  34     $ su - dyndns -s /bin/bash
  35     $ mkdir ~/.ssh
  36
  37 4. Prevent showing login messages::
  38
  39     $ su - dyndns -s /bin/bash
  40     $ touch ~/.hushlogin
  41
  42    Alternatively, you may commend out the "motd" lines in ``/etc/pam.d/sshd``
  43 5. Configure ssh-dyndns as root::
  44
  45     $ cp /usr/local/src/ssh-dyndns/ssh-dyndns.sh.config-dist /etc/ssh-dyndns.sh
  46     $ nano /etc/ssh-dyndns.sh
  47
  48 6. Allow ssh-dyndns to run "sudo make" without password::
  49
  50     $ visudo
  51     dyndns  ALL= NOPASSWD: /usr/bin/make
  52
  53
  54 Client
  55 ======
  56 On a machine at home, or which other IP you want to dyndns, setup a new ssh key
  57 as one of your users::
  58
  59     $ mkdir ~ssh-dyndns
  60     $ cd ~/ssh-dyndns
  61     $ ssh-keygen -N "" -C "dyndns@home.example.org" -f ~/ssh-dyndns/ssh-dyndns_rsa
  62
  63 Copy the contents of the public key (``ssh-dyndns_rsa.pub``) into
  64 ``/home/dyndns/.ssh/authorized_keys`` on your server.
  65
  66 Run the next command manually to confirm the new ssh key::
  67
  68     $ cd ~/ssh-dyndns/ && ssh -i ssh-dyndns_rsa dyndns@example.org home.example.org
  69
  70 If that worked, and you DNS entry worked, add the command to cron::
  71
  72     $ crontab -e
  73     # update dns entry home.example.org every 5 minutes
  74     */5 * * * *  cd /home/$user/ssh-dyndns/ && ssh -i ssh-dyndns_rsa dyndns@example.org home.example.org
  75
  76
  77 Configuration
  78 =============
  79 The configuration file template ``ssh-dyndns.sh.config-dist`` may be copied
  80 to either ``/etc/ssh-dyndns.sh`` or ``~/.config/ssh-dyndns.sh``.
  81
  82 The system-wide config file is loaded first, the user-specific one after that.
  83
  84 The configuration file may define the following variables:
  85
  86 ``data_dir``
  87     Path to the tinydns zone files, e.g. ``/etc/tinydns/root/``
  88 ``file_pattern``
  89     File name template. ``%DOMAIN%`` will be replaced with the actual
  90     domain name.
  91
  92     Default: ``data-dyndns-%DOMAIN%``
  93 ``timeout``
  94     DNS entry TTL (time to live) in seconds
  95
  96     Default: 300
  97 ``domain_patterns``
  98     Defines patterns for domains that may be dynamically changed.
  99     If the domain name does not match the pattern, the script aborts.
 100
 101     You may use several patterns by separating them with a space.
 102     Shell wildcards are supported (``*`` and ``?``).
 103
 104     Default: ``home.example.org *.home.example.org``
 105
 106
 107 =====
 108 Usage
 109 =====
 110 Simply ssh into the server and pass the hostname as parameter::
 111
 112     $ ssh dyndns@example.org home.example.org
 113
 114 This will start the ``ssh-dyndns`` script on the remote server, generate
 115 the tinydns zone file and run ``make`` in the ``data_dir`` directory to
 116 compile the ``data.cdb`` file.
 117 tinydns will automatically pick up the change.
 118
 119
 120 Check time of last update
 121 =========================
 122 ::
 123
 124     $ dig +short home.example.org ANY
 125     "Last update 2013-08-21 21.21.28+02.00."
 126     123.45.67.89
 127
 128
 129 Test
 130 ====
 131 You can test it locally:
 132
 133 1. Create config file::
 134
 135      $ cp ssh-dyndns.sh.config-dist ~/.config/ssh-dyndns.sh
 136
 137 2. Create dummy makefile::
 138
 139      $ touch /tmp/Makefile
 140
 141 3. Run it::
 142
 143      $ SSH_CLIENT=192.168.1.4 SSH_CONNECTION=1 ./ssh-dyndns foo home.example.org
 144
 145 4. See generated file::
 146
 147      $ cat /tmp/data-dyndns-home.example.org
 148
 149 ====
 150 Bugs
 151 ====
 152 - IPv6 is not supported yet
 153
 154
 155 =======
 156 License
 157 =======
 158 ssh-dyndns is licensed under the `AGPL v3`__ or later.
 159
 160 __ http://www.gnu.org/licenses/agpl.html
 161
 162
 163 ======
 164 Author
 165 ======
 166 Written by Christian Weiske, cweiske@cweiske.de