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
  14 tinydns is part of the dbjdns/dbndns package.
  15
  16
  17 =====
  18 Setup
  19 =====
  20
  21 Server
  22 ======
  23 1. Clone ssh-dyndns into a sensible location, e.g. ``/usr/local/src/ssh-dyndns``::
  24
  25     $ cd /usr/local/src/ && git clone git://git.cweiske.de/ssh-dyndns.git
  26
  27 2. Create a user with ``ssh-dyndns`` as login shell::
  28
  29     $ useradd -g nogroup -m -N -s /usr/local/src/ssh-dyndns/ssh-dyndns dyndns
  30
  31 3. Prepare password-less ssh keys for the dyndns user::
  32
  33     $ su - dyndns -s /bin/bash
  34     $ mkdir ~/.ssh
  35
  36 4. Prevent showing login messages::
  37
  38     $ su - dyndns -s /bin/bash
  39     $ touch ~/.hushlogin
  40
  41    Alternatively, you may commend out the "motd" lines in ``/etc/pam.d/sshd``
  42 5. Configure ssh-dyndns as root::
  43
  44     $ cp /usr/local/src/ssh-dyndns/ssh-dyndns.sh.config-dist /etc/ssh-dyndns.sh
  45     $ nano /etc/ssh-dyndns.sh
  46
  47 6. Allow ssh-dyndns to run "sudo make" without password::
  48
  49     $ visudo
  50     dyndns  ALL= NOPASSWD: /usr/bin/make
  51
  52
  53 Client
  54 ======
  55 On a machine at home, or which other IP you want to dyndns, setup a new ssh key
  56 as one of your users::
  57
  58     $ mkdir ~ssh-dyndns
  59     $ cd ~/ssh-dyndns
  60     $ ssh-keygen -N "" -C "dyndns@home.example.org" -f ~/ssh-dyndns/ssh-dyndns_rsa
  61
  62 Copy the contents of the public key (``ssh-dyndns_rsa.pub``) into
  63 ``/home/dyndns/.ssh/authorized_keys`` on your server.
  64
  65 Run the next command manually to confirm the new ssh key::
  66
  67     $ cd ~/ssh-dyndns/ && ssh -i ssh-dyndns_rsa dyndns@example.org home.example.org
  68
  69 If that worked, and you DNS entry worked, add the command to cron::
  70
  71     $ crontab -e
  72     # update dns entry home.example.org every 5 minutes
  73     */5 * * * *  cd /home/$user/ssh-dyndns/ && ssh -i ssh-dyndns_rsa dyndns@example.org home.example.org
  74
  75
  76 Configuration
  77 =============
  78 The configuration file template ``ssh-dyndns.sh.config-dist`` may be copied
  79 to either ``/etc/ssh-dyndns.sh`` or ``~/.config/ssh-dyndns.sh``.
  80
  81 The system-wide config file is loaded first, the user-specific one after that.
  82
  83 The configuration file may define the following variables:
  84
  85 ``data_dir``
  86     Path to the tinydns zone files, e.g. ``/etc/tinydns/root/``
  87 ``file_pattern``
  88     File name template. ``%DOMAIN%`` will be replaced with the actual
  89     domain name.
  90
  91     Default: ``data-dyndns-%DOMAIN%``
  92 ``timeout``
  93     DNS entry TTL (time to live) in seconds
  94
  95     Default: 300
  96 ``domain_patterns``
  97     Defines patterns for domains that may be dynamically changed.
  98     If the domain name does not match the pattern, the script aborts.
  99
 100     You may use several patterns by separating them with a space.
 101     Shell wildcards are supported (``*`` and ``?``).
 102
 103     Default: ``home.example.org *.home.example.org``
 104
 105
 106 =====
 107 Usage
 108 =====
 109 Simply ssh into the server and pass the hostname as parameter::
 110
 111     $ ssh dyndns@example.org home.example.org
 112
 113 This will start the ``ssh-dyndns`` script on the remote server, generate
 114 the tinydns zone file and run ``make`` in the ``data_dir`` directory to
 115 compile the ``data.cdb`` file.
 116 tinydns will automatically pick up the change.
 117
 118
 119 ====
 120 Bugs
 121 ====
 122 - IPv6 is not supported yet
 123
 124
 125 =======
 126 License
 127 =======
 128 ssh-dyndns is licensed under the `AGPL v3`__ or later.
 129
 130 __ http://www.gnu.org/licenses/agpl.html
 131
 132
 133 ======
 134 Author
 135 ======
 136 Written by Christian Weiske, cweiske@cweiske.de