Skip to content

Latest commit

 

History

History
106 lines (76 loc) · 7.06 KB

README.md

File metadata and controls

106 lines (76 loc) · 7.06 KB
Raw

Background

The current version of Avahi (v0.8) publishes the host name as a Domain Name System (DNS) Address (A) Record, which is sufficient for the majority of small, local network needs. However, sometimes additional names for host are needed. This is especially true now that Docker has simplified deployment of many services on a single host. This is where avahi-aliases-rs comes in.

The original implementation of Avahi aliases was an example Python script published in the Avahi wiki. Although the wiki is no longer available; the original script is preserved on the Internet Archive.

The original script spawned many versions. So, why another version? The motivations behind this version include:

  • A fast, compiled version runs with fewer resources. (This version is about half the memory of the Python version.)
  • Fewer installed executables; one per function: the daemon and the alias manager.
  • Improved error handling and messaging.
  • Syslog logging (and possibility other lagging facilities in the future).
  • Configurable connections timeouts, DNS record time-to-live, etc.

System Requirements

avahi-aliases-rs should build and build and run on most Unix-like operating systems on which Avahi and Rust also work. Some of the unit and integration tests only succeed when the Avahi daemon is available.

Installation

Installing avahi-daemon-rs currently requires building it on the target machine. (Technically, it could be cross-compiled, but there is not support in the existing Cargo.toml and Makefile.) For quick installation, follow these steps:

Prerequisites

  1. Make sure Avahi is installed and works correctly.
  2. Install Rust and ensure it works.
  3. Clone this GitHub repository (https://github.com/scott-ainsworth/avahi-aliases-rs.git).

Build

The remaining steps are executed from a shell prompt.

  1. Change to the avahi-aliases-rs directory (which was created by git clone).
  2. Run cargo build --release.

Install

  1. (optional) Test using the Pre-Installation Testing instructions below.
  2. Uninstall or disable existing Avahi aliases implementations1 (if any).
  3. Run sudo bin/install-systemd. The daemon (avahi-alias-daemon will start automatically).
  4. Use avahi-alias to add and remove CNAMEs (aliases).

Adding and Removing Aliases (CNAMEs)

The avahi-alias program is used to add and remove aliases. Examples:

  • avahi-alias add example.local adds example.local to the Avahi aliases file1. The addition should be picked up by the daemon within 10 seconds2.
  • avahi-alias remove example.local removes example.local from the Avahi aliases file1. The removal should be picked up by the daemon within 10 seconds2.
  • avahi-alias list lists the aliases in /etc/avahi/avahi-aliases. Invalid aliases are flagged in the listing.

Pre-installation Testing

To test the avahi-alias-daemon prior to installing it,

  1. Create an aliases file (test-aliases for example).
  2. Add an alias (target/release/avahi-alias add -f test-aliases example.local).
  3. Run the daemon (target/releases/avahi-alias-daemon -f test-aliases -v). If working, the daemon loading report loading and publishing the aliases.
  4. Open another shell windows and ping the alias (ping -c 1 example.local).
  5. Press control-C to terminate the daemon.

Getting Started Notes

  1. The default location for the Avahi aliases file is /etc/avahi/avahi-aliases. This can be changed with the --file option.
  2. Changes to /etc/avahi/avahi-aliases will be reflected in about 10 seconds. This time can be changed with the --poll command line option.

Compatibility with other Avahi Alias implementations

Given the wide variety of Avahi alias implementations, compatibility is a challenge. avahi-aliases-rs features and their compatibility are described in the following table.

Feature Compatibility
Aliases are stored in /etc/avahi/avahi‑aliases. Most, but not all, Python versions also use /etc/avahi-aliases. Some Python versions load any file in the /etc/avahi/aliases.d directory (this version does not).
Aliases file format. The basic format used by most versions is one aliases per line. avahi-aliases-rs extends this by allowing comments. Everything after a hash sign # is ignored. (Thus, the line example.local # comment is valid.) Additionally, invalid aliases stop the avahi-alias add and remove actions and are ignored by the daemon.
Internationalized Domain Names (IDNA) Not currently support. Support is planned.
Daemon runs as systemd service. Other versions also include support for System V/init.d or nothing at all. (There is no technical reason avahi-aliases-rs cannot support init.d; none of my systems currently use init.d and I cannot test it.)
Plays well with other versions. Probably not. The names of the executables (avahi-alias and avahi-alias-daemon) probably conflict with many other versions (installing avahi-aliases-rs could clobber other versions). The name of the systemd service is avahi-aliases, which is also used by some of the Python versions.
Syslog logging No Python version (that I know of) implements syslog logging.

Copyright and License

avahi-aliases-rs is Copyright © 2022 by Scott G. Ainsworth. Like Avahi, avahi-aliases-rs is licensed under the GNU Lesser General Public License, Version 2.1, February 1999. A copy of the license is available in the repository.

Acknowledgements and References