The NIS how-to on Debian
------------------------

0. INTRODUCTION.

  This HOWTO describes:

  1.  How to setup a NIS client-only system
  2.  How to configure your system to use NIS for users, groups and hosts
  3.  How to setup a NIS master server
  4.  Shadow passwords
  5.  How to setup a NIS slave server
  6.  How to setup a NIS server for broadcast
  7.  The /etc/default/nis configuration file
  8.  NIS security considerations
  9.  NIS binary database considerations

1. HOW TO SETUP A LOCAL NIS CLIENT

  1.1 Install the rpcbind and ypbind-mt packages. This is done automagically
      when installing the nis all-in-one meta-package, but it is also
	  possible to install ypbind-mt directly.

  1.2 The setup procedure requires defining your NIS domainname. This
      is just a name which describes the group of systems that use NIS, it
      is not a hostname. Please consult your network administrator to
      find the appropriate setting for your network.

      The domainname must be stored in the config file /etc/defaultdomain.

	  Unlike DNS hostnames and domainnames, the NIS domainname is
	  case-sensitive! The /etc/defaultdomain is an historical conventional
	  configuration file used since SUN Solaris times. Debian also
	  introduced the /etc/default/nis file to optionally configures other options
	  related to NIS setup, via multiple environment variables.

	  	echo 'my_nice_domain' | sudo tee /etc/defaultdomain

      The domainname could also be set dynamically before the NIS services
	  start, e.g. by using a DHCP hook to write the /etc/defaultdomain
	  file, but that is definitively a responsability of the administrator.

  1.3 If your NIS server is not "local" to your network, you will have to do
      some fine tuning. The ypbind process has a configuration file called
      /etc/yp.conf. You can hardcode a NIS server there - for more info
      see the manual page for ypbind(8). As an alternative ypbind can
	  broadcast a request to find an available server, but you need
	  to configure at least one server in the LAN in a compatible way,
	  as explained in section 6. The broadcast configuration is definitively
	  not recommended in most cases.

      *NOTE NOTE NOTE* - if you put a servername in /etc/yp.conf, make
      sure the server is also in /etc/hosts, or put it in in dotted-quad
      notation (12.34.56.78). Otherwise if your system boots and the
      network is not yet up or DNS isn't reachable, ypserv cannot resolve
      the servers in /etc/yp.conf and will hang!

  1.4 Start NIS by typing:

       systemctl enable ypbind.service
       systemctl start ypbind.service

  1.5 Follow the instructions in section 2 in order to configure your
      system to use NIS for account information.

2. HOW TO CONFIGURE YOUR SYSTEM TO USE NIS FOR USERS, GROUPS AND HOSTS:

  2.1 FOR LIBC6:

     Ensure to have libnss-nis package installed. It is currently
     only recommended by both libc and ypbind-mt, because it is not an
     essential component for the system. Even, for your own reasons you
     could be interested in binding a NIS domain to access the NIS maps via
     yptools, but not activating it as an account information provider for
     the system.
      
      Check your /etc/nsswitch.conf file and make sure that the entries for
      passwd, group, shadow and netgroup look like this:

      passwd:   compat
      group:    compat
      shadow:   compat
      netgroup: nis

      At this moment, libc6 has some troubles with reading netgroup data
      from files. So do not use "db" or "files" in the entry for netgroup,
      all netgroup lookups have to go through the NIS server.

  2.2 USERS: Add the following line to /etc/passwd on your NIS
      clients (at the end of the file):

      +::::::

      You can also use the + and - characters to include/exclude or change
      users.  If you want to exclude the user guest just add -guest to your
      /etc/passwd file.  You want to use a different shell (e.g. ksh) for
      the user "linux"?  No problem, just add "+linux::::::/bin/ksh"
      (without the quotes) to your /etc/passwd.  Fields that you don't want
      to change have to be left empty.

      For example, to only allow login-access to miquels,dth and ed, but to
      have the account data of all other users available:

      +miquels::::::
      +ed::::::
      +dth::::::
      +:*:::::/etc/NoShell

      Note that in Linux you can also override the password field, as we did
      in this example.

      If you are using shadow passwords and export a "shadow" map from
      your NIS server, you also want to put the following in /etc/shadow
      (again at the end of the file):

      +::::::::

      If you want to override the password field and you're using shadow
      passwords do it in /etc/shadow, not in /etc/passwd ofcourse.

  2.3 GROUPS: Add the following line to /etc/group (at the end):

      +:::

  2.4 HOSTS:

      Normally you should not do host lookups through NIS, use DNS for that.
      If you really must use NIS for it, here's how to do it.

      Edit /etc/nsswitch.conf and change the hosts entry:

        hosts:  files nis

3. HOW TO SETUP A MASTER NIS SERVER:

  3.0 Setup the defaultdomain as in section 1.2.

  3.1 Install the ypserv package. This is automagically done by installing
      the all-in-one nis package. You'll also need other packages such
      as rpcbind, but the Debian dependency system will take care
      of that automatically.

  3.2 Make sure that _all_ systems you are going to use as a NIS server,
      master or slave, have all other systems in the /etc/hosts file.
      This is because NIS does not use DNS. The FQDN (Fully Qualified
      Domain Name) should be the first hostname after every IP address,
      followed by just the hostname (without the domainname). For
      example:

        192.168.88.10	troi.cistron.nl	troi

      On the NIS server the NIS hosts file (which is usually just /etc/hosts)
      should also have this setup. You should also ensure that the
      entry for 127.0.0.1 in /etc/hosts does not include the hostname of
      the system. Not doing so can cause the NIS server to report
      localhost as the master server, making some operations fail. For
      example:

        127.0.0.1	localhost.localdomain	localhost

  3.3 set your NIS domain in the /etc/defaultdomain file. The NIS domain
      is just a name which describes the group of systems that use NIS, it
      is not a hostname.

	  	echo 'my_nice_domain' | sudo tee /etc/defaultdomain

	  It is common practice to use your DNS domainname
      for this.  Many people say this is a security risk, as by knowing your
      domainname it is possible to query your NIS server remotely and
      download all your NIS maps. Do not try to prevent this by choosing
      an obscure domainname. Just setup your /etc/ypserv.securenets and/
      or your /etc/ypserv.conf properly so that your NIS server cannot
      be accessed outside of your local network at all.

  3.4 You do NOT need to set ypserv to master (NISSERVER=master)
	  in /etc/default/nis, it is present only for historical reasons.

  3.5 As mentioned above, add your local network number to the file
      /etc/ypserv.securenets.  You don't _have_ to do this: the default
      is to allow everybody to access your NIS server. It is however
      *strongly* recommended.

      For added security you might also want to edit the /etc/ypserv.conf
      file to mangle the password file for some clients (do not do this
      if you have non-debian slave servers in your network!)

  3.6 Start the server by typing:

      systemctl enable ypserv.service
      systemctl enable yppasswdd.service
      systemctl enable ypxfrd.service

      systemctl start ypserv.service
      systemctl start yppasswdd.service
      systemctl start ypxfrd.service

     This will start the server (ypserv), the password daemon (yppasswdd),
	 and the maps transfer accellerator daemon (ypxfrd).

  3.7 Setup the server.

     You do this by typing "/usr/lib/yp/ypinit -m".

      systemctl restart ypxfrd.service

     This will start the server (ypserv), the password daemon (yppasswdd),
	 and the maps transfer accellerator daemon (ypxfrd).

	 Note that ypinit uses /var/yp/Makefile to update maps and you can
	 adapt that makefile to specifi uses.

     If you want to restrict access to your NIS server, you'll have to setup
     the NIS server as a client as well by running ypbind and adding the
     plus-entries to /etc/passwd _halfway_ the password file. The library
     functions will ignore all normal entries after the first NIS entry, and
     will get the rest of the info through NIS. This way the NIS access rules
     are maintained. example:

     root:x:0:0:root:/root:/bin/bash
     daemon:*:1:1:daemon:/usr/sbin:
     bin:*:2:2:bin:/bin:
     sys:*:3:3:sys:/dev:
     sync:*:4:100:sync:/bin:/bin/sync
     games:*:5:100:games:/usr/games:
     man:*:6:100:man:/var/catman:
     lp:*:7:7:lp:/var/spool/lpd:
     mail:*:8:8:mail:/var/spool/mail:
     news:*:9:9:news:/var/spool/news:
     uucp:*:10:50:uucp:/var/spool/uucp:
     nobody:*:65534:65534:noone at all,,,,:/dev/null:
     +miquels::::::
     +:*:::::/etc/NoShell
     [ All normal users AFTER this line! ]
     tester:*:299:10:Just a test account:/tmp:
     miquels:1234567890123:101:10:Miquel van Smoorenburg:/home/miquels:/bin/zsh

    The user tester will exist, but have a shell of /etc/NoShell. miquels
    will have normal access.

    Alternatively, you could edit the /var/yp/Makefile file and set NIS to
    use another source password file by pointing the YPPWDDIR variable at the
    top of the Makefile to another directory than /etc. On big systems, the
    NIS password and group files are often stored in /var/yp/ypfiles/. If
    you do this the normal tools to administrate the password file such as
    "passwd", "chfn", "adduser" will not work anymore and you will need
    special homemade tools for this.

    However yppasswd, ypchsh and ypchfn will work of course, provided you
    run the yppasswdd with the -D option to point it to the location of the
    NIS password and shadow file. In version 3.9 and up of the Debian packages,
    you can set this in the /etc/default/nis configuration file - the name
    of the variable is YPPWDDIR, just like in /var/yp/Makefile.

    The Debian version of these utilities - and the yppasswdd daemon -
    have a non-standard extension. "Root" can - using the root password -
    change other people's passwords, finger info and shell. If you edit
    the NIS password file manually or you use the standard /etc/passwd
    file, remember that after every change in one of the NIS source files
    you'll have to run "make" in the /var/yp directory to update the
    NIS maps. It would be reasonable to do this nightly from cron to be
    sure the NIS maps are kept up-to-date.

4. SHADOW PASSWORDS

  Libc6 has real shadow support for NIS builtin. It works like you would
  expect; export the shadow map from the NIS server and just use it.
  The shadow map should be built with the "-s" (secure) option to
  makedbm. This is automatic in all modern /var/yp/Makefile files.

  Note that if you use the shadow password file you need to add
  "plus" entries (as in 2.2) to both /etc/passwd and /etc/shadow.
  Make sure you use the correct format; the passwd and shadow files
  have different fields.

  On the master server the /var/yp/Makefile file needs to include
  the shadow file in the "all:" target. If you're using the sample
  /var/yp/Makefile this is done automatically - it autodetects
  /etc/shadow and builds/exports it if it exists.

5. HOW TO SETUP A NIS SLAVE SERVER

  5.1 First setup your system as a working NIS client (see 1.)

  5.2 Follow the steps 3.0 .. 3.5 as described in above, but at step 3.4
      set ypserv to slave (NISSERVER=slave) in the /etc/default/nis file.
	  Again this is obsoleted by use of systemctl setup, and present there
	  only for historical reasons and support the old sysv init script.

  5.3 Tell your master NIS server it has a slave. First you have to adjust
      the NIS Makefile *on the master* so that all future updates get
      distributed to the slave(s) automatically. Set the NOPUSH variable
      in /var/yp/Makefile to "false" like this:

       NOPUSH="false"

      (Don't you just hate double negatives ..) Now tell the master about
      its slaves by running "/usr/lib/yp/ypinit -m". Enter the names of the
      slave servers. The maps will get rebuilt, but not pushed to the slaves
      just yet.

  5.4 Start the slave and initialize it by entering:

      systemctl enable ypserv.service
      systemctl start ypserv.service
      /usr/lib/yp/ypinit -s <name_of_your_master_nis_server_here>

      The slave server will transfer the maps from the master.

  5.5 You might want to use the following commands

      systemctl enable ypxfr_1perday.timer
	  systemctl enable ypxfr_1perhour.timer
	  systemctl enable ypxfr_2perday.timer
      systemctl start ypxfr_1perday.timer
	  systemctl start ypxfr_1perhour.timer
	  systemctl start ypxfr_2perday.timer

      This will ensure that most NIS maps are kept up-to-date, even if an
      update is missed because the slave was down at the time the update was
      done on the master.

6.  HOW TO SETUP NIS SERVER FOR BROADCAST

  Talking about NIS setup, the Debian 10+ default NIS server configuration
  prevents the clients being able to work in broadcast mode (its default).
  You have a couple of alternatives: either specifying an explicit server
  IP address in /etc/yp.conf on the NIS client (i.e. not use broadcasting),
  or add `-r` to rpcbind daemon on - at least - one of the NIS servers.

  That could be done as follows:

       echo "OPTIONS=-w -r" >>/etc/default/rpcbind
       systemctl daemon-reload

  on the server(s), *before* running any client ypbind. This can also be used on
  each server in order to configure it as a client of itself: in that case, the
  best thing to do is usually using the loopback address 127.0.0.1
  in /etc/yp.conf. Finally - even if not mandatory - it is often convenient in small
  networks having most/all clients even acting as slave servers, because that
  would render the net more resilient against temporary master unavailability.

7. THE /etc/default/nis CONFIGURATION FILE

  The Debian system traditionally provided a set of configuration environment
  variables in /etc/default/nis. That is now totally optional, but still
  useful if default values need to be overriden for some reasons. The
  NISSERVER and NISCLIENT vars are still there, but are NOT used anymore
  when using systemd services. The traditional sysv init scripts are 
  provided as courtesy scripts for people who still use init and they still
  use the two variables for historical reasons. So, both
  ypserv and ypbind-mt come with their init scripts for each daemon.
  The alternative would be renaming the S link in K link in /etc/rcX.d 
  for each YP service not in use.
  As consequence, the nis courtesy package could also be not installed 
  at all on new boxes, because the only truly useful stuff it provides 
  is this document :-)

8. NIS SECURITY CONSIDERATIONS

  Note that NIS allows all clients to download users' shadow passwords in
  encrypted mode, in merged or not merged form. The only other form of
  protection is that provided by listing allowed client IPs in /var/yp/securenets.
  This is intrinsecally a weak form of security, so NIS should be used as is only
  in trustable networks, well protected by intruders. Eventually, it is
  possibile to use NIS with Kerberos to avoid the use of system
  shadow passwords for authentication and use Kerberos tickets instead, which
  adds one more layer of complexity to the system and implies that the
  admin needs to keep two different databases in sync. This is not
  conceptually different from what can be done with a LDAP+Kerberos setup,
  but for using libnss-nis instead of libnss-ldap.

9. NIS BINARY DATABASE CONSIDERATIONS AND UPGRADES

  The NIS database files are compiled in GDBM format and shared among 
  servers and clients. From time to time, the GDBM binary format could be 
  broken during updates of the library, due to changes in the library itself
  or the tool chain that builds it. It happened in the past (see bug 
  https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=984560) and could 
  happen again in the future. While other (more robust) formats could be adopted 
  in the NIS services, the GDBM one is the most diffused among multple archs and
  platforms. That potentially exposes to having broken implementations when
  multiple versions of NIS programs, even built with different compilers, are used 
  in the same network. It could specifically happen at upgrade time from
  stable to the new stable Debian OS, even. You are warned about that, because
  the GDBM format is not portable among multiple implementations and archs,
  sorry. Specifically:

--

       nis.debian.howto  3.10-1  15-Nov-2003  miquels@cistron.nl
                         4.0+  Jan-2021  frankie@debian.org