<?xml version="1.0" encoding="UTF-8"?>
<chapter id="installation">
  <title>Installation</title>

  <warning>
    <para>Before upgrading from Netatalk 2 or 3 to Netatalk 4, please read the
    <link linkend="upgrade">upgrading</link> chapter in this manual.</para>
  </warning>

  <sect1>
    <title>How to obtain Netatalk</title>

    <para>Please have a look at the <ulink url="https://netatalk.io">Netatalk
    homepage</ulink> for the most up to date information on where to find the
    latest version of the software.</para>

    <sect2>
      <title>Binary packages</title>

      <para>Binary packages of Netatalk are included in the package
      repositories of some Linux, BSD, and Solaris-like distributions.
      Installing Netatalk through this channel will give you the most seamless
      experience, with managed updates when new package versions are
      available.</para>

      <para>You might also want to have a look at 3rd party package
      repositories for your operating system, such as <ulink
      url="https://rpmfind.net/">rpmfind</ulink> for Red Hat based Linux
      distributions, <ulink url="https://www.opencsw.org/">OpenCSW</ulink> for
      Solaris and its descendants, and <ulink url="https://brew.sh/">
      Homebrew</ulink> or <ulink url="https://www.macports.org/">MacPorts
      </ulink> for macOS.</para>
    </sect2>

    <sect2>
      <title>Source packages</title>

      <sect3>
        <title>Tarballs</title>

        <para>Prepackaged tarballs with stable releases of the Netatalk source
        code are available on the <ulink
        url="https://github.com/Netatalk/netatalk/releases">Netatalk releases
        page on GitHub</ulink>.</para>
      </sect3>

      <sect3>
        <title>Git</title>

        <para>Downloading the Git repository can be done quickly and
        easily:</para>

        <orderedlist>
          <listitem>
            <para>Make sure you have Git installed. <command>which
            git</command> should produce a path to git.</para>

            <screen><prompt>$</prompt> <userinput>which git</userinput>
<computeroutput>/usr/bin/git</computeroutput></screen>
          </listitem>

          <listitem>
            <para>Now get the source:</para>

            <screen><prompt>$</prompt> <userinput>git clone https://github.com/Netatalk/netatalk.git netatalk-code
</userinput><computeroutput>Cloning into 'netatalk-code'...
remote: Enumerating objects: 41592, done.
...
Resolving deltas: 100% (32227/32227), done.
</computeroutput></screen>

            <para>This will create a local directory called
            <filename>netatalk-code</filename> containing a complete and fresh
            copy of the whole Netatalk source tree from the Git
            repository.</para>
          </listitem>

          <listitem>
            <para>If you don't specify a branch or tag, you will get the
            bleeding edge development code. In order to get the latest stable
            Netatalk 3.1 code, for instance, check out the branch named
            "branch-netatalk-3-1":</para>

            <screen><prompt>$</prompt> <userinput>git checkout branch-netatalk-3-1</userinput></screen>
          </listitem>

          <listitem>
            <para>In order to keep your repository copy updated, occasionally
            run:</para>

            <screen><prompt>$</prompt> <userinput>git pull</userinput></screen>
          </listitem>
        </orderedlist>
      </sect3>
    </sect2>
  </sect1>

  <sect1>
    <title>Compiling Netatalk</title>

    <sect2>
      <title>Prerequisites</title>

      <sect3>
        <title>Required third-party software</title>

        <itemizedlist>
          <listitem>
            <para>Berkeley DB<indexterm>
                <primary>BDB</primary>

                <secondary>Berkeley DB</secondary>
              </indexterm></para>

            <para>The default dbd CNID backend for netatalk uses Berkeley DB
            to store unique file identifiers. At the time of writing you need
            at least version 4.6.</para>

            <para>The recommended version is 5.3, the final release under the
            permissive Sleepycat license, and therefore the most widely
            distributed version.</para>
          </listitem>

          <listitem>
            <para>libevent</para>

            <para>Internal event callbacks in the netatalk service controller
            daemon are built on libevent version 2.</para>
          </listitem>

          <listitem>
            <para>Libgcrypt</para>

            <para>The <ulink url="https://gnupg.org/software/libgcrypt/">
            Libgcrypt</ulink> library supplies the encryption for the standard
            User Authentication Modules (UAMs). They are: DHX2, DHCAST128
            (a.k.a. DHX) and RandNum.</para>
          </listitem>
        </itemizedlist>
      </sect3>

      <sect3>
        <title>Optional third-party software</title>

        <para>Netatalk can use the following third-party software to enhance
        its functionality.</para>

        <itemizedlist>
          <listitem>
            <para>ACL and LDAP</para>

            <para>LDAP is an open and industry-standard user directory
            protocol that works in tandem with the advanced permissions scheme
            of ACL. On some operating systems ACL and LDAP libraries are built
            in to the system, while on others you have to install supporting
            packages to enable this functionality.</para>
          </listitem>

          <listitem>
            <para>Avahi or mDNSresponder for Bonjour</para>

            <para>Mac OS X 10.2 and later uses Bonjour (a.k.a. Zeroconf) for
            automatic service discovery. Netatalk can advertise AFP file
            sharing and Time Machine volumes by using Avahi or
            mDNSResponder.</para>

            <para>When using Avahi, D-Bus is also required, and the Avahi
            library must have been built with D-Bus support.</para>
          </listitem>

          <listitem>
            <para>cmark-gfm</para>

            <para>CommonMark is used to translate markdown to plain text,
            which is useful for installing or packaging Netatalk's
            READMEs.</para>
          </listitem>

          <listitem>
            <para>CrackLib</para>

            <para>When using the Random Number UAMs and netatalk's own
            <userinput>afppasswd</userinput> password manager, CrackLib can
            help protect against setting weak passwords for authentication
            with netatalk.</para>

            <para>The CrackLib dictionary, which is sometimes distributed
            separately in a runtime package, is also a requirement.</para>
          </listitem>

          <listitem>
            <para>D-Bus</para>

            <para>D-Bus provides a mechanism for sending messages between
            processes, used by multiple Netatalk features: Spotlight, Zeroconf
            with Avahi, and the <userinput>afpstats</userinput> tool.</para>
          </listitem>

          <listitem>
            <para>DocBook XSL and xsltproc</para>

            <para>The Netatalk documentation, including this manual, are
            authored in XML format. DocBook XSL stylesheets and xsltproc are
            used to transcode the XML to other human-readable formats such as
            troff (for man pages), html, or pdf. Note that the DocBook XSL
            stylesheets have to be non-namespaced.</para>
          </listitem>

          <listitem>
            <para>GLib and GIO</para>

            <para>Used by the <userinput>afpstats</userinput> tool to
            interface with D-Bus.</para>
          </listitem>

          <listitem>
            <para>iconv</para>

            <para>iconv provides conversion routines for many character
            encodings. Netatalk uses it to provide charsets it does not have
            built in conversions for, like ISO-8859-1. On glibc systems,
            Netatalk can use the glibc provided iconv implementation.
            Otherwise you can use the GNU libiconv implementation.</para>
          </listitem>

          <listitem>
            <para>Kerberos V</para>

            <para>Kerberos v5 is a client-server based authentication protocol
            invented at the Massachusetts Institute of Technology. With the
            Kerberos library, netatalk can produce the GSS UAM library for
            authentication with existing Kerberos infrastructure.</para>
          </listitem>

          <listitem>
            <para>MySQL or MariaDB</para>

            <para>By leveraging a MySQL-compatible client library, netatalk
            can be built with a MySQL CNID backend that is highly scalable and
            reliable. The administrator has to provide a separate database
            instance for use with this backend.</para>
          </listitem>

          <listitem>
            <para>PAM<indexterm>
                <primary>PAM</primary>

                <secondary>Pluggable Authentication Modules</secondary>
              </indexterm></para>

            <para>PAM provides a flexible mechanism for authenticating users.
            PAM was invented by SUN<indexterm>
                <primary>SUN</primary>

                <secondary>Sun Microsystems</secondary>
              </indexterm> Microsystems. Linux-PAM is a suite of shared
            libraries that enable the local system administrator to choose how
            applications authenticate users.</para>
          </listitem>

          <listitem>
            <para>Perl</para>

            <para>Netatalk's administrative utility scripts rely on the Perl
            runtime, version 5.8 or later. The required Perl modules include
            <emphasis>IO::Socket::IP</emphasis> (asip-status) and
            <emphasis>Net::DBus</emphasis> (afpstats).</para>
          </listitem>

          <listitem>
            <para>TCP wrappers</para>

            <para>Wietse Venema's network logger, also known as TCPD or
            LOG_TCP.</para>

            <para>Security options are: access control per host, domain and/or
            service; detection of host name spoofing or host address spoofing;
            booby traps to implement an early-warning system.</para>
          </listitem>

          <listitem>
            <para>Tracker, or TinySPARQL / LocalSearch</para>

            <para>Netatalk uses <ulink
            url="https://tracker.gnome.org">Tracker</ulink> or its later
            incarnation TinySPARQL/<ulink
            url="https://gnome.pages.gitlab.gnome.org/localsearch/">LocalSearch
            </ulink> as the metadata backend for Spotlight<indexterm>
                <primary>Spotlight</primary>
              </indexterm> search indexing. The minimum required version is
            0.7 as this was the first version to support <ulink
            url="https://gnome.pages.gitlab.gnome.org/tracker/">SPARQL</ulink>.</para>
          </listitem>

          <listitem>
            <para>talloc / bison / flex</para>

            <para>Samba's talloc library, a Yacc parser such as bison, and a
            lexer like flex are also required for Spotlight.</para>
          </listitem>

          <listitem>
            <para>UnicodeData.txt</para>

            <para>The build system uses Perl and the Unicode Character
            Database to generate Netatalk's Unicode character conversion
            sources.</para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>

    <sect2 id="compiling-netatalk">
      <title>Configure and build<indexterm>
          <primary>Compile</primary>

          <secondary>Compiling Netatalk from Source</secondary>
        </indexterm> Netatalk</title>

      <para>Instructions on how to use the build system to configure and build
      netatalk source code are documented in the <ulink
      url="https://github.com/Netatalk/netatalk/blob/main/INSTALL.md">INSTALL.md</ulink>
      file in the Netatalk source tree.</para>

      <para>For examples of concrete steps to compile on specific operating
      systems, refer to the <link linkend="compile">Compile Netatalk from
      Source</link> appendix in this manual, which is automatically generated
      from the CI build scripts.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Starting and stopping Netatalk</title>

    <para>The Netatalk distribution comes with several operating system
    specific startup script templates that are tailored according to the
    options given to the build system before compiling. Currently, templates
    are provided for systemd, openrc, in addition to platform specific scripts
    for popular Linux distributions, BSD variants, Solaris descendants, and
    macOS.</para>

    <para>When building from source, the Netatalk build system will attempt to
    detect which init style is appropriate for your platform. You can also
    configure the build system to install the specific type of startup
    script(s) <indexterm>
        <primary>Startscript</primary>

        <secondary>startup script</secondary>
      </indexterm> you want by specifying the <option>with-init-style</option>
    option. For the syntax, please refer to the build system's help
    text.</para>

    <para>Since new Linux, *BSD, and Solaris-like distributions appear at
    regular intervals, and the startup procedure for the other systems
    mentioned above might change as well, it is a good idea to not blindly
    install a startup script but to confirm first that it will work on your
    system.</para>

    <para>If you use Netatalk as part of a fixed setup, like a Linux
    distribution, an RPM or a BSD package, things will probably have been
    arranged properly for you. The previous paragraphs therefore apply mostly
    for people who have compiled Netatalk themselves.</para>

    <para>The following daemon need to be started by whatever startup script
    mechanism is used:</para>

    <itemizedlist>
      <listitem>
        <para>netatalk<indexterm>
            <primary>netatalk</primary>
          </indexterm></para>
      </listitem>
    </itemizedlist>

    <para>In the absence of a startup script, you can also launch this daemon
    directly (as root), and kill it with SIGTERM when you are done with
    it.</para>

    <para>Additionally, make sure that the configuration file
    <filename>afp.conf</filename> is in the right place. You can inquire
    netatalk where it is expecting the file to be by running the
    <userinput>netatalk -V</userinput> command.</para>

    <para>If you want to run AppleTalk services, you also need to start the
    <command>atalkd</command> daemon, plus the optional
    <command>papd</command>, <command>timelord</command>, and
    <command>a2boot</command> daemons. See the <link
    linkend="appletalk">AppleTalk</link> chapter in this manual for more
    information.</para>
  </sect1>
</chapter>
