scott-ainsworth / avahi-aliases-rs Goto Github PK

2.0 1.0 0.0 239 KB

Announce Avahi aliases (CNAMEs) on your local network.

License: GNU Lesser General Public License v2.1

Makefile 5.88% Rust 90.17% Shell 3.96%

avahi cname-record mdns

avahi-aliases-rs's Introduction

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

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

Build

The remaining steps are executed from a shell prompt.

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

Install

(optional) Test using the Pre-Installation Testing instructions below.
Uninstall or disable existing Avahi aliases implementations¹ (if any).
Run sudo bin/install-systemd. The daemon (avahi-alias-daemon will start automatically).
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 file¹. The addition should be picked up by the daemon within 10 seconds².
avahi-alias remove example.local removes example.local from the Avahi aliases file¹. The removal should be picked up by the daemon within 10 seconds².
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,

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

Getting Started Notes

The default location for the Avahi aliases file is /etc/avahi/avahi-aliases. This can be changed with the --file option.
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

Avahi web site.
Original Python example on the Avahi wiki (archived version at the Internet Archive. The original is no longer available.)
Airtonix (Zeno) Python implementation on GitHub. Based on the Avahi example. Earliest implementation on GitHub.
luarntlemercier implementation on GitHub. Includes systemd service unit configuration file, installer, and uninstaller.

avahi-aliases-rs's People

Contributors

Stargazers

Watchers

avahi-aliases-rs's Issues

Efficient alias file change detection

Currently, avahi-alias-deamon polls for changes to /etc/avahi/avahi-aliases, which is primitive and inefficient. Two possibilities for change detection are subscribing to file system events, signalling, and service restart.

Discussion

Event subscription: File system event subscription is efficient. However, it varies by operating system and can fail (e.g., due to capacity limits). Thus, a fall back is needed. The fall back could be polling or signaling.

Signalling: Sending a daemon a HUP signal is a long-standing method to have a daemon reload data. However, it only notifies under limited circumstances. In this case, when avahi-alias makes changes. Editing the aliases files directly will not send a signal to the daemon. Thus, a fall back is needed. This is likely to be service restart.

Service Restart: This is built in to both systemd and init.d.

Requirements

Choose a change detection method.
Implement change detection

Housekeeping

Requirements

Exclude .rustfmt from spell check.
Synchronize Makefile and tasks.json build options to minimize rebuilds.
Makefile inconsistencies cleanup.
Add issue number to in-code to-do comments.

Write README.md

Write the initial README.md:

Project description
Version 1 goals
Contribution
References
Credits

Level up testing coverage on lib.rs

Testing line coverage on the library is spotty.

Add syslog to logging module

For the daemon, the option to send log entries to syslog (vice the console) is needed.

Add init_syslog()

The syslog module can generate multiple error types.

Add LoggingError enum to manage the error types.

`avahi-alias-daemon` fails with is-empty error when `avahi-aliases` is empty

When the avahi-aliases file is empty, avahi-aliases-daemon attempts to commit the Avahi entry group anyway. The commit returns an is-empty status, which is interpreted as a failure. Instead, a warning should be logged and the daemon should continue to execute.

Encode IDNA names

References

IETF RFC 5891
Internationalized domain name on Wikipedia

Reduce size of binaries

The binaries (avahi-alias and avahi-alias-daemon) seem much larger than their functionality should require. There is much discussion of this, but no solutions for distribution that achieve anything comparable to C with shared libraries.

References

min-sized-rust documentation on Github.
Making executables smaller discussion on Rust users forum.

Implement unit tests for `messaging`

The messaging lacks unit tests.

Implement unit tests for the compute_log_level() function.
Correct resulting bugs.

Implement GitHub actions to build and unit test

Follow Avahi publishing guidelines

The way CNAMEs are currently published is a hack inherited from the origin Python example. Modify the code to follow the rules.

References

https://www.avahi.org/doxygen/html/#good_publish

Refactor `options` into library

The command-line options code originated in avahi-alias. Parts are now duplicated in avahi-alias-daemon. Achieve DRY principles by refactoring the code into the library:

Move the avahi-alias options module into the library.
Delete the avahi-alias-daemon options.
Rename options.Args to options.CommandOpts.
Expose CommonOpts, Command, and CommandOpts.
Update avahi-alias to use CommandOpts.
Update avahi-alias-daemon to use CommonOpts.
Create unit tests.

Cleanup lib.rs and modules

The visibility and naming of modules, structs, functions, etc. in the avahi-aliases library evolved somewhat randomly over time.

Clean up public symbols.
Rename public symbols as needed for good semantic naming.

daemon `--ttl` and other options should have range validation

Problem

Currently the --polling-interval, --timeout, and --ttl options accept any u64 value.

Requirements

Add range validation for --polling-interval: 10 – 60 seconds.
Add range validation for --timeout: 10 – 300 seconds.
Add range validation for --ttl: 0 – 2³¹-1 seconds.

Create unit tests for `AliasesFile`

AliasesFile is central to the correct operation of both avahi-alias and avahi-alias-daemon. However, it lacks unit tests.

`avahi-alias` does not set exit status

avahi-alias does not set exit status. Set exit status to 0 on success and 1 on error.

Flatten the `aliases` module

The aliases module has only two structs yet the module is in a subdirectory. Consider moving the structs directly under src/.

Support /etc/avahi/avahi-aliases.d

Background

Some other implementations of avahi-aliases support loading additional aliases from files in /etc/avahi/avahi-aliases.d. Although avahi-alias supports editing these files (using the --file option), avahi-alias-daemon does not use them.

Requirements

Modify avahi-alias-daemon to load aliases from files in /etc/avahi/avahi-aliases.d.
Allow a command-line option to change the directory.
Allow a command-line option to disable loading aliases from the directory.

Refactor Avahi client code into separate module

Currently, the library is a mix of specialized support for the binaries (avahi-alias and avahi-alias-daemon) and a rudimentary Avahi D-Bus client. Separating the Avahi D-Bus client code will simplify using a third-party library of generated code. Additionally, the generated D-Bus code should be a submodule of the Avahi D-Bus client.

Requirements

Refactor the Avahi client code into an independent package.

Leverage cargo's build-in strip for release builds

Currently, a Makefile file is to strip release binaries. However, Cargo now has this built in (requires +nightly).

Requirements

Switch from using Make to Cargo's built-in capability.

Create an installer for systemd environment

Cleanup lint management

Currently, lints are handled using the nightly version of Rust and enables lints only available in the nightly version. Additionally, many normally-allowed lints are enabled by adding #![warn(...)] lines to the source (which is ugly).

Requirements

Enable lints in .cargo/config.toml.
Cleanup code to eliminate lints.

Expose `AliasesFile` directly instead of under `aliases` module

Currently, binaries must use AliasesFile via its module (i.e., use aliases::AliasesFile). Since the library is simple, exposing AliasesFile directly.

Add `--timeout` option to the daemon

Background

The D-Bus connection timeout is is currently fixed at 60 seconds.

Requirements

Add a command line option to set the timeout.

Move unit tests into `test` submodules

Moving unit tests into submodules eliminates false "not used" messages.

Move options unit tests
Move lines unit tests

Implement daemon

Implement resource record module
Implement CNAME encoding
Implement resource record encoding
Implement and test syslog logging
Add syslog command line options

Add `--ttl` option to the daemon

Background

The time-to-live (TTL) for CNAMEs is currently fixed at 60 seconds.

Requirements

Add a command line option to set the TTL.

`avahi-alias` error messages are displayed in debug form

The avahi-alias command displays error message (e.g., "No such file or directory") in debug form. They should be displayed in a more human-friendly form.

Refactor messaging into the library as logging

Logging for avahi-aliases and avahi-aliases-daemon differs only in the destination of the log entries. This difference can be handled through two separate initializations.

Rename messaging to logging
Move logging into the library
Rename init() to init_console().

Change CNAME to Alias

Technically, an alias is a CNAME. However, in Avahi CNAMEs have been called aliases for long enough for the term to stick. Thus, instead of using alias vice CNAME reduces the learning/communication curve.

Upgrade sysinfo and syslog packages

Upgrade the

sysinfo package to 0.22.2 and
syslog package to 6.0.0.

Note: syslog changes the type of syslog::Formatter3164::pid from i32 to u32, while sysinfo::get_current_pid() still return i32.

Aliases must be validated

Currently, an alias comprises all provided characters less leading and trailing whitespace. This can yield invalid aliases (e.g., my alias.local)

Requirements

Validate all aliases, both in the aliases file and specified on the command line, meet naming requirements.
avahi-alias list must flag invalid aliases in the alias listing.
avahi-alias add must make no changes when invalid aliases are found on the command line or in the aliases file.
avahi-alias remove must make no changes when invalid aliases are found on the command line.
avahi-alias remove must make no changes when invalid aliases are found in the aliases files unless the --remove-invalid option is specified.
avahi-alias remove --force must remove all invalid aliases from the aliases file.
avahi-alias-daemon must log and ignore invalid aliases found in the aliases file.

Notes

It is not clear if non-.local CNAMES are allowed by the specification or in practical application. Since RFC 6762 indicates that using Multicast DNS for non-.local domains is a fail-over option that should be disabled by default, version 1 will only allow .local CNAMES.

References

IETF RFC 6762

Modify error::ErrorWrapper to minimize long-term borrows

Currently, error::ErrorWrapper borrows most string values. Since ErrorWrapper needs to be passed up the stack for handling in user-aware code, this leads to nearly-impossible-to-resolve lifetime issues.

Modify all ErrorWrapper enum variants to make copies of references.

Version 1 Roadmap

`avahi-alias` Command Line Utility Requirements

Add, remove, and list aliases (avahi-alias command).
Ignore comments and extraneous whitespace in aliases files.
Overhaul error:ErrorWrapper to minimize borrows. #15
Validate aliases. #14

`avahi-alias-daemon` Requirements

Overview: #6
Operate at the command line.
Operate under systemd.
Log to syslog if requested. #12
Poll for alias file changes (vice hooking to file system change events).
Specify polling interval (--poll-time option, default: 5 sec.). #36

Common requirements

Write README.md. #1
Specify the alias file to use (--file option, default: /etc/avahi/avahi-aliases)
Specify the level of verbosity (--verbose option or --quiet option, default: false)
Specify debug-level logging (--debug option, default: false)

Add integration test for `avahi-alias`

Currently there are no integration tests for the alias managers (avahi-alias) or daemon (avahi-alias-daemon).

Requirements

Test the add command.
Test the remove command.
Test the list command.
Ensure all three work if comments exist.

Finalize licensing

Determine which license(s) to allow. MIT and Apache are popular. Avahi itself is GNU Lesser.

Requirements

Update the license files.
Add licensing header to source files.

Version 1.1 Roadmap

Functionality

Encode IDNA names #24
Follow Avahi publishing guidelines #30
Add --ttl option to the daemon #46
Add --timeout options to the daemon #47
General housekeeping #51
Add integration test for avahi-alias #53
Validate --poling-interval, --timeout, and --ttl` #56
Upgrade third-party packages #58
Cleanup lints #59

Process and Delivery

Implement GitHub actions to verify pull requests #26
Implement GitHub actions to create releases

Add polling interval daemon option

Currently avahi-alias-daemon checks for alias file changes every 5 seconds.

Requirements

Add a --poll-interval command line option.
Change the default to 30 seconds.

Notes

Ultimately, instead of polling, (1) the daemon could subscribe to file system events or (2) avahi-alias could signal a change (HUP?) #37

Merge LoggingError into ErrorWrapper

LoggingError is the original error wrapper and is now OBE. Merge it into ErrorWrapper.

scott-ainsworth / avahi-aliases-rs Goto Github PK

avahi-aliases-rs's Introduction

Background

System Requirements

Installation

Adding and Removing Aliases (CNAMEs)

Pre-installation Testing

Getting Started Notes

Compatibility with other Avahi Alias implementations

Copyright and License

Acknowledgements and References

avahi-aliases-rs's People

Contributors

Stargazers

Watchers

avahi-aliases-rs's Issues

Discussion

Requirements

References

References

References

Background

Requirements

Requirements

Requirements

Notes

References

avahi-alias Command Line Utility Requirements

avahi-alias-daemon Requirements

Common requirements

Requirements

Requirements

Notes

Recommend Projects

Recommend Topics

Recommend Org

`avahi-alias` Command Line Utility Requirements

`avahi-alias-daemon` Requirements