Avahi Zeroconf

From Official Kodi Wiki
Jump to navigation Jump to search
Home icon grey.png   ▶ File sharing ▶ Avahi Zeroconf

Avahi is a system which facilitates service discovery on a local network via the mDNS/DNS-SD protocol suite, which together are branded as ZeroConf. This enables Kodi (beginning with v11 "Eden") to recognize media sources present on your local network without being explicitly configured for where the sources are located and what protocol is used. Compatible technology is built-in to Apple MacOS (branded as Bonjour) and installers are also available for Windows, Linux and derivates like BSD.


Installation

  • Linux:
    • Debian-based (APT): From a terminal emulator, execute the command

      sudo apt -y install avahi-daemon avahi-discover libnss-mdns && sudo systemctl enable --now avahi-daemon.service

    • Fedora-based (DNF/YUM): From a terminal emulator, execute the command

      sudo dnf install avahi avahi-tools nss-mdns && sudo systemctl enable --now avahi-daemon.service

    • Arch-based (PACMAN): From a terminal emulator, execute the command

      pacman -Syu avahi && sudo systemctl enable --now avahi-daemon.service

  • *BSD:
    • FreeBSD: From a terminal emulator, execute the command

      pkg install avahi-app avahi-libdns nss_mdns


Services supported by Kodi

Kodi can receive ZeroConf announcements for services operating over the following protocols:

  • Server Message Block/Common Internet File System (SMB/CIFS)
  • File Transfer Protocol (FTP)
  • Home Television Streaming Protocol (HTSP)
  • Web-based Distributed Authoring and Versioning (WebDAV)
  • Network File System (NFS)
  • Secure File Transfer Protocol (SFTP)
  • Digital Audio Access Protocol (DAAP)


Most HTSP (e.g. Tvheadend), SMB/CIFS (e.g. Samba v3.3+), WebDAV (e.g. PhoDAV) and DAAP (e.g. iTunes v4.0+, Ampache v3.8.0+) servers have support for ZeroConf built-in. This means that these services should be announced automatically when the Avahi daemon is also installed and enabled on the device running them, and no static service announcement configuration should be needed.


Static service announcements

For services which don't support ZeroConf registration, there is an easy method to make Avahi aware of them and similarly announce them.

Each service whose announcements are being manually configured needs to be represented by a file placed in the folder named services within the Avahi sysconfig directory (located by default at /etc/avahi). These files can be written/edited in any plain text editor and should follow the naming convention <service name>.service, where "<service name>" may consist of any non-whitespace ASCII characters which allow the system administrator to easily recognize them, with contents that conform to the XML 1.0 specification.

The Kodi ZeroConf browser supports TXT records (see the official DNS-SD ServiceTypes under "Defined TXT keys"), which Avahi can include with each service announcement and may contain the configuration details needed for clients to access them. Specifically, Kodi can parse the path (URL), u (Username) and p (Password) keys, and if those details are sufficient to connect to a service, it should be displayed in the File Browser automatically the first time Kodi runs.

Note: The Avahi daemon has to run on the same server which hosts the services which should be announced.

The section below has some sample configurations which would allow static announcements for the supported protocols. For general information according to the config files see the avahi.service(5) man page.


Sample service configurations

Network File System (NFS) server

The following configuration would announce an NFS server (operating on the default NFS port 2049) with the exported path /path/to/nfsexport. The Kodi ZeroConf Browser would show this entry as NFS server at <name of server>. The "%h" is a substitution variable which gets replaced by the hostname of the device providing the service. When examining this entry, Kodi would show the available path on that service as the following URL: nfs://<ip of server>:2049/path/to/nfsexport/

/etc/avahi/services/nfs.service
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">NFS server at %h</name>  
  <service>
    <type>_nfs._tcp</type>
    <port>2049</port>
    <txt-record>path=/path/to/nfsexport</txt-record>
  </service>
</service-group>


Web-based Distributed Authoring and Versioning (WebDAV) server

The following configuration would announce a WebDAV server (in this case, via an Apache web server on TCP port 80) with the accessible path /webdav/path. The Kodi ZeroConf Browser would show this entry as WebDAV on <name of server>. When examining this entry, Kodi would show the available path on that service as the following URL: dav://<ip of server>:80/webdav/path/

/etc/avahi/services/webdav.service
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">WebDav on %h</name>  
  <service>
    <type>_webdav._tcp</type>
    <port>80</port>
    <txt-record>path=/webdav/path</txt-record> 
  </service>
</service-group>

 

Secure File Transfer Protocol (SFTP over SSH) server

The following configuration would announce an SSH server with SFTP enabled (on the default TCP port 22) with an accessible path /path/to/be/accessed, the user account sshuser and account password sshpass. The Kodi ZeroConf Browser would show this entry as SFTP on <name of server>. When examining this entry, Kodi would show the available path on that service as the following URL: sftp://sshuser:sshpass@<ip of server>:22/path/to/be/accessed/

/etc/avahi/services/sftp.service
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">SFTP on %h</name>
  <service>
    <type>_sftp-ssh._tcp</type>
    <port>22</port>
    <txt-record>path=/path/to/be/accessed</txt-record>
    <txt-record>u=sshuser</txt-record>
    <txt-record>p=sshpass</txt-record>  
  </service>
</service-group>


File Transfer Protocol (FTP) server

The following configuration would announce an FTP server (on the default TCP port 21) with an accessible path /ftppath, the user account ftpuser and account password ftppass. The Kodi ZeroConf Browser would show this entry as FTP on <name of server>. When examining this entry, Kodi would show the available path on that service as the following URL: ftp:/ftpuser:ftppass@<ip of server>:21/ftppath/

/etc/avahi/services/ftp.service 
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">FTP on %h</name>
  <service>
    <type>_ftp._tcp</type>
    <port>21</port>
    <txt-record>path=/ftppath</txt-record>
    <txt-record>u=ftpuser</txt-record>
    <txt-record>p=ftppass</txt-record>
  </service>
</service-group>


Server Message Block/Common Internet File System (SMB/CIFS) server

Note: This Avahi service file would only be needed if running a version of Samba prior to v3.3.x, as subsequent versions provide configuration keys to manage the servers ZeroConf announcements from within its own primary configuration file 'smb.conf'.

The following configuration would announce a Samba server (on the default TCP port 445). The Kodi ZeroConf Browser would show this entry as Samba on <name of server>. When examining this entry, Kodi would show the available shares as the contents of the following URL: smb://<ip of server>:445

/etc/avahi/services/smb.service
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">SAMBA on %h</name>
  <service>
    <type>_smb._tcp</type>
    <port>445</port>  
  </service>
</service-group>


External links

For more detailed information, please visit avahi.org.