add man pages and github actions (#1)

.github/workflows/auto-tag.yml

@@ -0,0 +1,27 @@
+name: Tagging main using pyproject.toml
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    name: Tag main using pyproject.toml
+    runs-on: ubuntu-20.04
+    steps:
+    - name: Checkout main
+      uses: actions/checkout@v3
+      with:
+        token: ${{ secrets.LXDDYNDNS_TAGGING_PAT }}
+    - name: The new tag
+      id: computed-tag
+      run: |
+        set -e
+        TAG=$(cat pyproject.toml \
+          | grep --extended-regexp "^version =" \
+          | grep --extended-regexp --only-matching "[0-9]+\.[0-9]+.[0-9]+[-\.\+a-zA-Z0-9]*" \
+          | head --lines=1)
+        echo "tag=v$TAG" >> "$GITHUB_OUTPUT"
+    - name: Tag main depending on the value in pyproject.toml
+      uses: djordon/[email protected]
+      with:
+        tag: ${{ steps.computed-tag.outputs.tag }}

.github/workflows/publish-pypi.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lxd-dyndns
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+          cache: pip
+      - name: Install dependencies
+        run: |
+          pip install --upgrade build twine
+      - name: Build distribution
+        run: |
+          python -m build
+      - name: Upload to PyPi
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test-python.yml

@@ -0,0 +1,33 @@
+name: Test python package
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test-python:
+    runs-on: ubuntu-latest
+    strategy:
+        matrix:
+          python-version:
+            - 3.11
+            - 3.12
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Setup python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pipx install pipenv
+          pipenv install --dev --python ${{ steps.setup-python.outputs.python-path }}
+      - name: Run tests
+        run: |
+          pipenv run pytest -vvvv -s

.gitignore

@@ -1,3 +1,7 @@
+# don't commit config files by mistake
+*.conf
+*.toml
+
 # don't care about openapi
 openapi/
 

Pipfile

@@ -13,6 +13,7 @@ lxd-dyndns = {file = "."}
 [dev-packages]
 black = "*"
 isort = "*"
+pytest = "*"
 
 [requires]
 python_version = "3.11"

man/lxd-dyndns.1

@@ -1,4 +1,4 @@
-.\" Copyright (c) 2023 Aisha Tammy <[email protected]>
+.\" Copyright (c) 2023-2024 Aisha Tammy <[email protected]>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -12,7 +12,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: April 30 2021 $
+.Dd $Mdocdate: January 9 2024 $
 .Dt LXD-DYNDNS 1
 .Os
 .Sh NAME
@@ -22,6 +22,7 @@
 .Nm lxd-dyndns
 .Op Fl d Ar debug_level
 .Op Fl f Ar file
+.Op Fl h , -help
 .Op Fl n
 .Sh DESCRIPTION
 .Nm
@@ -33,13 +34,24 @@ The options are as follows:
 .Bl -tag -width Ds -compact
 .It Fl d Ar debug_level
 .Pp
-Set the debug level of output.
+Set the debug level of output .
+Valid options are
+.Ar debug ,
+.Ar info ,
+.Ar warn ,
+.Ar error
+or
+.Ar critical .
 .It Fl f Ar file
 .Pp
 Specify an alternative configuration file.
 The default is
 .Pa /etc/lxd-dyndns.conf .
 .Pp
+.It Fl h , -help
+.Pp
+Show the help message and exit.
+.Pp
 .It Fl n
 .Pp
 Configtest mode.

man/lxd-dyndns.conf.5

@@ -1,4 +1,4 @@
-.\" Copyright (c) 2023 Aisha Tammy <[email protected]>
+.\" Copyright (c) 2023-2024 Aisha Tammy <[email protected]>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -12,16 +12,122 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: April 30 2021 $
+.Dd $Mdocdate: January 9 2024 $
 .Dt LXD-DYNDNS.CONF 5
 .Os
 .Sh NAME
 .Nm lxd-dyndns.conf
-.Nd lxd-dyndns configuration file
+.Nd Configuration file for
+.Xr lxd-dyndns 1
 .Sh DESCRIPTION
 .Nm
 is the configuration file for
-.Xr lxd-dyndns 1 .
+.Xr lxd-dyndns 1 ,
+which is read from
+.Pa /etc/lxd-dyndns.conf
+by default.
 .Pp
-The configuration file follows the toml format, divided into two top level
-categories, lxd-credentials and projects.
+The configuration file follows the
+.Cm toml
+format, divided into two categories, top level options and per project options.
+Both categories support the same set of options, and per project options can
+override the top level options.
+.Pp
+Currently the following options are supported:
+.Pp
+.Bl -tag -width Ds -compact
+.It cache_dir
+.Pp
+Path to the directory used for storing the program cache.
+The default value is
+.Pa /var/lib/lxd-dyndns .
+.Pp
+.It dns_key_name
+.Pp
+TSIG key ID used for dynamic DNS queries to the nameserver.
+.Pp
+.It dns_key_secret
+.Pp
+TSIG key secret used for dynnamic DNS queries to the nameserver.
+.Pp
+.It dns_port
+.Pp
+Port number that the DNS server is listening on.
+The default is
+.Ar 53 .
+.Pp
+.It dns_server
+.Pp
+IP address or FQDN of the DNS server to use for managing records.
+The default is
+.Ar 127.0.0.1 .
+.Pp
+.It dns_transport
+.Pp
+Protocol to use for connecting to the nameserver.
+Choices are
+.Ar TCP
+or
+.Ar UDP .
+The default is
+.Ar UDP .
+.Pp
+.It dns_zone
+.Pp
+DNS zone under which to create the instance records.
+.Pp
+.It ipv4_prefixes
+.Pp
+A list of valid IPv4 prefixes, that will be used to filter IPs on instances and
+will be added to the DNS records.
+.Pp
+.It ipv6_prefixes
+.Pp
+A list of valid IPv6 prefixes, that will be used to filter IPs on instances and
+will be added to the DNS records.
+.Pp
+.It lxd_server
+.Pp
+API endpoint for the LXD server.
+.Pp
+.It lxd_client_cert
+.Pp
+Public certificate used for authentication to the API endpoint by the client.
+.Pp
+.It lxd_client_key
+.Pp
+Private certificate used for authentication to the API endpoint by the client.
+.Pp
+.It lxd_verify
+.Pp
+Boolean to control if the client should verify the API endpoint's certificate.
+The default is
+.Ar true .
+.Pp
+.It refresh_interval
+.Pp
+Time delay, in seconds, between refreshing data for a project.
+The default is
+.Ar 30 .
+.El
+.Sh EXAMPLES
+.Bd -literal -offset width
+cache_dir = "/var/lib/lxd-dyndns"
+
+[projects.k8s]
+dns_server = "192.168.2.1"
+dns_port = 8053
+dns_transport = "TCP"
+dns_key_name = "knot_lxd"
+dns_key_secret = "Zj7NdR9/6DJonRuTt/++QgMyvSlD4Ndv+i5SvGtGY3Q="
+dns_zone = "lxd.domain.tld."
+
+lxd_server = "https://lxd-leader.domain.tld:8443"
+lxd_verify = false
+lxd_client_cert = "/etc/ssl/lxd-dyndns/client.crt"
+lxd_client_key = "/etc/ssl/lxd-dyndns/client.key"
+
+ipv6_prefixes = [ "dead:beef::0/96" ]
+.Ed
+.Sh SEE ALSO
+.Xr lxd-dyndns 1

src/lxd_dyndns/run.py

@@ -15,7 +15,11 @@
 
 parser = argparse.ArgumentParser(description="LXD dynamic DNS client")
 parser.add_argument(
-    "-f", metavar="file", type=str, help="config file", default="/etc/lxd-dyndns.conf"
+    "-f",
+    metavar="file",
+    type=str,
+    help="config file, see `man 5 lxd-dyndns.conf` for details",
+    default="/etc/lxd-dyndns.conf",
 )
 parser.add_argument("-n", action="store_true", help="configtest mode")
 parser.add_argument(