Difference between revisions of "Avahi Zeroconf"

From Official Kodi Wiki
Jump to navigation Jump to search
m (thanks for the update roguescholar)
 
(14 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{XBMC faq toc Inline}}
{{mininav| [[File sharing]] }}
__TOC__
== General ==
=== What is Avahi (Zeroconf) ===
<section begin="intro"/>Avahi is a system which facilitates service discovery on a local network via the mDNS/DNS-SD protocol suite. This enables XBMC to recognize media sources inside your local network without knowing where the sources are located and what protocol is used. Compatible technology is found in Apple MacOS X (branded Bonjour and sometimes Zeroconf). Avahi is available for linux and derivates (BSD) afaik.<section end="intro"/>


For more details have a look at [http://www.avahi.org avahi.org].
'''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 [[Archive:XBMC v11 (Eden) changelog|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.


=== Installing ===
== Installation ==
Since the Installation of Avahi depends on the used operating system please realise that this page only covers the configuration of static service announcements (for services which don't have avahi support included). For installation instructions just use a www search engine with the keywords "install avahi on <enter operting system here".
* '''{{Big|Microsoft Windows:}}
** '''''Vista/7/8/8.1/10/11:'''''<blockquote>Install [https://support.apple.com/kb/dl999?locale=en_US Bonjour Print Services for Windows v2.0.2]</blockquote>


== Services supported by XBMC ==
* '''{{Big|Linux:}}'''
** '''''Debian-based (APT):''''' From a terminal emulator, execute the command<blockquote><code>sudo apt -y install avahi-daemon avahi-discover libnss-mdns && sudo systemctl enable --now avahi-daemon.service</code></blockquote>
** '''''Fedora-based (DNF/YUM):''''' From a terminal emulator, execute the command<blockquote><code>sudo dnf install avahi avahi-tools nss-mdns && sudo systemctl enable --now avahi-daemon.service</code></blockquote>
** '''''Arch-based (PACMAN):''''' From a terminal emulator, execute the command<blockquote><code>pacman -Syu avahi && sudo systemctl enable --now avahi-daemon.service</code></blockquote>


XBMC can receive service announcements for the following protocols. [[Windows File Sharing (SMB/SAMBA/CIFS)|samba]], [[Media Source FTP|FTP]], [[HTS Tvheadend|HTSP]], [[iTunes (DAAP)]] , WEBDAV, [[NFS]] and [[SFTP]] (ssh server).
* '''{{Big|*BSD:}}'''
** '''''FreeBSD:''''' From a terminal emulator, execute the command<blockquote><code>pkg install avahi-app avahi-libdns nss_mdns</code></blockquote>


The most HTSP, samba (minimum version 3.3.x), WEBDAV and iTunes (DAAP) servers are supposed to have support for zeroconf built in. This means that these services should be announcent automatically when avahi is installed. No static service announcement configuration should be needed then.
== 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)
<br />
Most HTSP (e.g. [https://tvheadend.org Tvheadend]), SMB/CIFS (e.g. [https://www.samba.org Samba] v3.3+), WebDAV (e.g. [https://wiki.gnome.org/phodav PhoDAV]) and DAAP (e.g. [https://www.apple.com/itunes/ iTunes] v4.0+, [https://ampache.org/ 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 announcement ==
== Static service announcements ==
=== What about it? ===
For services which don't support ZeroConf registration, there is an easy method to make Avahi aware of them and similarly announce them.
For services which don't support zeroconf registration there is an easy possibility to make avahi announce them. For each service which should be announced there has to be a configuration file. Normally these files should reside in /etc/avahi/services and end with the file extension ".service". The XBMC zeroconf browser supports txt-records. This means that it can parse some of the official DNS-SD keys (see [http://www.dns-sd.org/ServiceTypes.html ServiceTypes] under "Defined TXT keys"). XBMC parses the "path","u"(username) and "p"(password) keys. This allows to specify a complete service including the path and account information for accessing it.


'''The Avahi daemon has to run on the same server which hosts the services which should be announced.'''
Each service whose announcements are being manually configured needs to be represented by a file placed in the folder named <code>services</code> within the Avahi sysconfig directory (located by default at <code>/etc/avahi</code>). These files can be written/edited in any plain text editor and should follow the naming convention <code><service name>.service</code>, 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 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 [http://avahi.org/download/avahi.service.5.xml official man page].
The Kodi ZeroConf browser supports TXT records (see the official DNS-SD [http://www.dns-sd.org/ServiceTypes.html 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 <code>path</code> (URL), <code>u</code> (Username) and <code>p</code> (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.


=== Sample service configurations ===
::{{Note|The Avahi daemon has to run on the same server which hosts the services which should be announced.}}


==== NFS service (/etc/avahi/services/nfs.service) ====
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 [https://linux.die.net/man/5/avahi.service avahi.service(5) man page].
The following configuration would announce a NFS server (with the nfs default port 2149) with the exported path ''/path/to/nfsexport''. XBMC Zeroconf browser would show this entry as ''NFS server at <name of server>''. The "%h" gets substituted by the hostname of the server. When clicking this entry - XBMC would show the available path on that service with ''/path/to/nfsexport''. Clicking on that one would generate the following url: '''nfs://<ip of server>:2049/path/to/nfsexport/'''


=== 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 <code>/path/to/nfsexport</code>. 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: '''<code style="white-space: pre;">nfs://<ip of server>:2049/path/to/nfsexport/</code>'''


  <?xml version="1.0" standalone='no'?>
: '''''/etc/avahi/services/nfs.service'''''
  <!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<blockquote><syntaxhighlight lang="xml">
  <service-group>
<?xml version="1.0" standalone='no'?>
    <name replace-wildcards="yes">NFS server at %h</name>   
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
    <service>
<service-group>
      <type>_nfs._tcp</type>
  <name replace-wildcards="yes">NFS server at %h</name>   
      <port>2149</port>
  <service>
      <txt-record>path=/path/to/nfsexport</txt-record>
    <type>_nfs._tcp</type>
    </service>
    <port>2049</port>
  </service-group>
    <txt-record>path=/path/to/nfsexport</txt-record>
 
  </service>
==== WEBDAV service (/etc/avahi/services/webdav.service) ====
</service-group>
The following configuration would announce a WebDAV server (e.x. apache at port 80) with the accessible path ''/webdav/path''. XBMC Zeroconf browser would show this entry as ''WebDav on <name of server>''. The "%h" gets substituted by the hostname of the server. When clicking this entry - XBMC would show the available path on that service with ''/webdav/path''. Clicking on that one would generate the following url: '''dav://<ip of server>:80/webdav/path/'''.
</syntaxhighlight></blockquote>


  <?xml version="1.0" standalone='no'?>
==== Web-based Distributed Authoring and Versioning (WebDAV) server ====
  <!DOCTYPE service-group SYSTEM "avahi-service.dtd">
The following configuration would announce a WebDAV server (in this case, via an Apache web server on TCP port 80) with the accessible path <code>/webdav/path</code>. 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: '''<code style="white-space: pre;">dav://<ip of server>:80/webdav/path/</code>'''
  <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>


==== SFTP service (/etc/avahi/services/sftp.service) ====
: '''''/etc/avahi/services/webdav.service'''''
The following configuration would announce a sftp/ssh server (on default port 22) with the accessible path ''/path/to/be/accessed'', the user ''sshuser'' and the password ''sshpass''. XBMC Zeroconf browser would show this entry as ''SFTP on <name of server>''. The "%h" gets substituted by the hostname of the server. When clicking this entry - XBMC would show the available path on that service with ''/path/to/be/accessed''. Clicking on that one would generate the following url: '''sftp://sshuser:[email protected]<ip of server>:22/path/to/be/accessed/'''.
<blockquote><syntaxhighlight lang="xml">
<?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>
</syntaxhighlight></blockquote>
 
==== 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 <code>/path/to/be/accessed</code>, the user account <code>sshuser</code> and account password <code>sshpass</code>. 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: '''<code style="white-space: pre;"><nowiki>sftp://sshuser:[email protected]<ip of server>:22/path/to/be/accessed/</nowiki></code>'''


  <?xml version="1.0" standalone='no'?>
: '''''/etc/avahi/services/sftp.service'''''
  <!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<blockquote><syntaxhighlight lang="xml">
  <service-group>
<?xml version="1.0" standalone='no'?>
    <name replace-wildcards="yes">SFTP on %h</name>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
    <service>
<service-group>
      <type>_sftp-ssh._tcp</type>
  <name replace-wildcards="yes">SFTP on %h</name>
      <port>22</port>
  <service>
      <txt-record>path=/path/to/be/accessed</txt-record>
    <type>_sftp-ssh._tcp</type>
      <txt-record>u=sshuser</txt-record>
    <port>22</port>
      <txt-record>p=sshpass</txt-record>
    <txt-record>path=/path/to/be/accessed</txt-record>
    </service>
    <txt-record>u=sshuser</txt-record>
  </service-group>
    <txt-record>p=sshpass</txt-record> 
  </service>
</service-group>
</syntaxhighlight></blockquote>
 
==== File Transfer Protocol (FTP) server ====
The following configuration would announce an FTP server (on the default TCP port 21) with an accessible path <code>/ftppath</code>, the user account <code>ftpuser</code> and account password <code>ftppass</code>. 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: '''<code style="white-space: pre;"><nowiki>ftp:/ftpuser:[email protected]<ip of server>:21/ftppath/</nowiki></code>'''


==== FTP service (/etc/avahi/services/ftp.service) ====
: '''''/etc/avahi/services/ftp.service''''' 
The following configuration would announce a FTP server (on default port 21) with the accessible path ''/ftppath'', the user ''ftpuser'' and the password ''ftppass''. XBMC Zeroconf browser would show this entry as ''FTP on <name of server>''. The "%h" gets substituted by the hostname of the server. When clicking this entry - XBMC would show the available path on that service with ''/ftppath''. Clicking on that one would generate the following url: '''ftp:/ftpuser:[email protected]<ip of server>:21/ftppath/'''.
<blockquote><syntaxhighlight lang="xml">
<?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>
</syntaxhighlight></blockquote>
 
==== 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 '<var>smb.conf</var>'.}}
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: '''<code style="white-space: pre;">smb://<ip of server>:445</code>'''


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


==== SAMBA service - pre 3.3.x (/etc/avahi/services/smb.service) ====
== External links ==
The following configuration would announce a SAMBA server (on default port 139). XBMC Zeroconf browser would show this entry as ''SAMBA on <name of server>''. The "%h" gets substituted by the hostname of the server. When clicking this entry - XBMC would show the available shares on that samba server.
For more detailed information, please visit '''[https://www.avahi.org/ avahi.org]'''.


  <?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>139</port> 
    </service>
  </service-group>


[[Category:File Sharing]]
{{updated|19}}
[[Category:File sharing]]

Latest revision as of 00:45, 3 September 2021

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.

1 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

2 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.

3 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.

3.1 Sample service configurations

3.1.1 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>

3.1.2 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>

 

3.1.3 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:[email protected]<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>

 

3.1.4 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:[email protected]<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>

 

3.1.5 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>

4 External links

For more detailed information, please visit avahi.org.