An easy-to-use service for making a host reachable by aliases in a LAN and advertise services via mDNS. Uses grandcat’s awesome zeroconf library.
Typically, in a LAN one machine has one hostname. In contrast to this, on the internet one server often serves multiple webpages and applications under different domains. Sometimes also multiple subdomains are used to separate the different offerings by the FQDN ('service01.example.com') instead of in the URL path ('example.com/service01'). This makes a lot of things easier. When hosting services in a local environment, domains are often not available and/or also overkill. Some applications will not run properly in local setups because of this or require additional work for the setup. This project makes it easy to make your services reachable under e.g. nextcloud.local and paperless.local instead of fumbling with my-nas.local/nextcloud. Your webapps get the rootpath they deserve!
The following diagram illustrates a typical setup where Hostaliasd enables clean domain-based access to multiple services running on a NAS:
flowchart LR
A{{seafile.local}}
B{{paperless.local}}
C{{photoprism.local}}
A --> proxy
B --> proxy
C --> proxy
subgraph NAS
proxy{Reverse Proxy}-->seafile
proxy-->paperless
proxy-->photoprism
subgraph "Container 1"
seafile[Seafile]
end
subgraph "Container 2"
paperless[Paperless]
end
subgraph "Container 3"
photoprism[Photoprism]
end
end
In this setup, Hostaliasd advertises each service under its own .local domain, making them easily accessible without port numbers or path-based routing.
Hostaliasd can not only advertise webapps but also different services and protocols. Want to see your self-built homeserver SMB share in the network tab of your file explorer? Advertise the presence of a smb server in the network. You don’t want to remember the IP address of your routers UI? Make it known in the network with a service. There are a lot of different use cases for mDNS.
The only runtime dependency is systemd.
Prerequisites: Go 1.26 or higher.
# Download dependencies
go mod download
# Build a snapshot package (creates .deb/.rpm in dist/)
go tool goreleaser release --snapshot --cleanInstall the generated package from dist/ as for your distribution.
# Installation (for x86_64/amd64)
sudo dpkg -i hostaliasd_*_linux_amd64.deb
# Installation (for ARM64)
sudo dpkg -i hostaliasd_*_linux_arm64.deb
# Check service status
hostaliasctl status# Installation (for x86_64/amd64)
sudo rpm -i hostaliasd_*_linux_amd64.rpm
# Installation (for ARM64)
sudo rpm -i hostaliasd_*_linux_arm64.rpm
# Check service status
hostaliasctl status# Debian/Ubuntu: remove package and configuration files
sudo apt remove --purge hostaliasd
# RedHat/CentOS/Fedora
sudo dnf remove hostaliasdThe --purge option (Debian/Ubuntu only) removes both the package and its configuration files. Without it, apt remove would keep configuration files in /etc/, dnf remove uninstalls the package and typically removes its files, including configuration.
Or build and install everything from hand:
# Build
go build ./cmd/hostaliasd
# Install binary and ctl symlink
sudo install -Dm0755 hostaliasd /usr/libexec/hostaliasd
sudo ln -sf /usr/libexec/hostaliasd /usr/bin/hostaliasctl
# Install service
sudo cp hostaliasd.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable hostaliasd
sudo systemctl start hostaliasdThe daemon binary is installed outside the normal user PATH at /usr/libexec/hostaliasd.
Use hostaliasctl for interactive CLI usage.
The CLI is available as hostaliasctl, which manages services and controls the daemon (start, stop, reload, status).
sudo hostaliasctl add --alias nextcloud --name NextcloudWithout an explicit --type Hostaliasd uses https by default (_https._tcp, port 443). That means nextcloud.local is advertised as a web service.
Inspect configuration:
$ sudo hostaliasctl list
[0] 'Nextcloud' of type '_https._tcp'
Advertised service hosts:
- nextcloud.local:443 (https://nextcloud.local)sudo hostaliasctl add --name 'My NAS' --type workstationIn order to make your machine reachable and pingable via its hostname (e.g, my-nas.local, find out by just running hostname in your terminal) you can use the workstation type.
$ sudo hostaliasctl list
[0] 'My NAS' of type '_workstation._tcp'
Advertised service hosts:
- my-nas.local:9hostaliasctl add --alias nextcloud --with-hostnameYou can include the hostname together with aliases with the --with-hostname flag.
sudo hostaliasctl add --name 'NAS Services' --alias seafile --alias opencloud --alias photoprismIn order to advertise multiple aliases, you can use it multiple times in the command.
$ sudo hostaliasctl list
[0] 'NAS Services' of type '_https._tcp'
Advertised service hosts:
- seafile.local:443 (https://seafile.local)
- opencloud.local:443 (https://opencloud.local)
- photoprism.local:443 (https://photoprism.local)hostaliasctl add --alias nextcloud --with-hostnameYou can include the hostname together with aliases with the --with-hostname flag.
Services you want to advertise don’t have to be on the same system. Use --advertise for this:
sudo hostaliasctl add --alias router --advertise 192.168.0.1
$ sudo hostaliasctl list
[0] 'Hostaliasd Service' of type '_https._tcp'
Advertised service hosts:
- router.local:443 (https://router.local)
Advertise addresses:
- 192.168.0.1sudo hostaliasctl add --alias printer04 --advertise 192.168.0.28 --type ipp --name "Printer 04"
sudo hostaliasctl add --type "_my-app._tcp" --port 1337 --name "My App"You can use shorthands or provide a custom service type, e.g. if you have a application that wants to discover other instances.
$ sudo hostaliasctl list
[0] 'Printer 04' of type '_ipp._tcp'
Advertised service hosts:
- printer04.local:631
Advertise addresses:
- 192.168.0.28
[1] 'My App' of type '_my-app._tcp'
Advertised service hosts:
- my-workstation.local:1337# Service control (via systemctl or hostaliasctl)
systemctl status|start|stop|restart hostaliasd
hostaliasctl start|stop|reload|status
# View logs
journalctl -u hostaliasd -rThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
See the LICENSE file for details.