Table Of Contents

Previous topic

Internet Account Replication

This Page

Internet Account Replication (IAR) - Manual

Peter Fedorow
Brian Tiffin
John Caldwell


IAR replicates POSIX user credentials over the Internet.

It is like NIS, but:

  • Is really easy to use – it practically works out of the box;
  • Works over the Internet – it is compatible with regular firewalls; and,
  • Uses SSH to encrypt the data flow, and GNU Privacy Guard to authenticate the data.


Separate credentials for every node


With IAR

One set of credentials from a master node


Comparison with NIS

NIS (a.k.a. yp) is a name service for Unix/Linux (hereafter referred to as *nix) credentials. The credentials is the data stored in the files: passwd, group, shadow, and (optionally) gshadow. Despite NIS’s lack of security, it is still in widespread use due to being easy to setup and administer when compared to LDAP, scales reasonably well, and is supported by nearly all forms of *nix.

Internet Account Replication (IAR) is intended to provide a modern alternative to NIS. It does not use RPC (portmapper) for data transport, instead it uses a ssh connection. The use of a SSH connection means the data is encrypted in transit, and only a single TCP port is used.



  • POSIX compatible OS (written to be easy to drop into, or port, to any POSIX OS, but only tested under GNU/Linux - Ubuntu and Fedora)
  • sh - dash, bash, or compatible
  • GNU Privacy Guard
  • ssh server
  • nixhash (alternatively for Debian-compatible distros only “mkpasswd” found in the ‘whois’ package)


  • GNU/POSIX compatible OS (main program is written to be easy to port, but the NSS module is only supported in GNU land). Tested under:

    • Ubuntu
    • Fedora
  • sh - dash, bash, or compatible

  • GNU Privacy Guard

  • ssh client

  • sshpass

Getting Started

IAR is available packaged as both .deb (for Debian/Ubuntu), and .rpm (for Fedora). If you are not running a .deb or .rpm-based system, we have designed the software to be easy to install from source. Directions are in the Installing From Source section.

(Need to add directions on how to point to the repo.)


Recommended: Ensure you have a sufficient supply of true random numbers in /dev/urandom. This is necessary to prevent key generation from hanging. This can be accomplished by setting up a hardware random number generator to feed /dev/urandom. If you do not have a hardware random number generator, install ‘haveged’.

Ubuntu / Debian / Devuan

Add the Repo

Create the file /etc/apt/sources.list.d/iar.list containing:

deb ./
Install Package Verification Key


sudo apt-key adv --keyserver --recv-keys EE56AC32AF86804F 3D1B4D6844E2DC44


apt-get update
apt-get install iar-server


apt-get update
apt-get install iar-client

Red Hat / Fedora



yum install iar-server


yum install iar-client


After installing the packages:


  1. Run:
    iar server-setup

    and follow the on-screen prompts.

  2. Set sshd on the server to listen on the default IAR port. Recommended port: 22322.
    nano /etc/ssh/sshd_config
    Port 22322
    Restart sshd with:
    service restart ssh

    Note: Do not change the existing Port 22 line unless you no longer want sshd to listen on port 22.

  3. If you want to change the password for the _iar user, (which is the account IAR clients use to login to the server,) type:
    passwd _iar

    Remember to set the client password to match in /etc/iar.conf. See Configuration File section for instructions about this.


  1. Run iar client-setup and follow the directions.
  2. If you changed the port from IAR’s default, alter the port number in /etc/iar/iar.conf.
  3. Approve the client on the server. iar approve. You may need to wait up to three (3) minutes because clients poll every three (3) minutes. Alternatively, on the client, type sudo iar client to immediately poll.


iar (fallback to default gateway IP)

Debugging Hints

  • Check the client status: On the client – sudo iar status
  • Check the server status: On the server – sudo iar status
  • The client will usually provide a useful error message when invoked in the foreground: On the client – sudo iar client
  • Check the logs on the server: cat /var/log/iar/iar-server.log and cat /var/log/iar/iar-server-laststatus.log
  • Check the logs on the client: cat /var/log/iar/iar-client.log and cat /var/log/iar/iar-client-laststatus.log

Still not working? Try e-mailing rai<reversed> AT to politely ask for help.


IAR builds upon SSH, and adds GNU Privacy Guard validation of the data sent from the master server to the clients. This protects against man-in-the-middle attacks due to both compromised network connections and compromised intermediary hosts.

Out of consideration of convenience for basic (not expert) users, IAR servers and clients install with a default password. This does not readily expose the data on the server to attack because any client attempting to talk to the server requires explicit approval on the server. (This is performed with the iar approve command.) However, the default password does enable an attacker to spoof the server, which means an approved client would login to it, thinking it is the actual server and send its authentication credentials to the fake server. The attacker could then take the captured client credentials, spoof the client’s IP, and replay the credentials to the real server to retrieve the replicated credentials, including password hashes from the server. This would require a moderate level of proficiency with networking, and a willingness to do so. Any reasonably determined attacker with access to your network can accomplish this. Though in most cases, it is easier to boot a workstation from a USB key, and copy the database off it.

To protect against the above described attack scenario, change the IAR client login password from the default to a strong password.

Note: Like NIS and LDAP – without the addition of a Kerberos authentication layer – retrieval of your password authentication hashes, such as from any compromised host on your network, means you are only secure if none of your users have passwords that cannot be cracked by the power of a bot-net of GPU-equipped PCs. As users tend to choose very weak passwords, be warned, and consider deploying a secure authentication layer.


Please see for some information on configuring ssh(secure shell) to be secure.

Key Recommendations

/etc/ssh/sshd_config settings:


# disable password authentication (AFTER more secure forms are in place)
PasswordAuthentication no



/etc/ssh/ssh_config settings:

# Github needs diffie-hellman-group-exchange-sha1 some of the time but not always.
#    KexAlgorithms,diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,diffie-hellman-group14-sha1

Host *
    PasswordAuthentication no

Configuration File

The configuration file (by default /etc/iar/iar.conf) contains script lines that are sourced into the IAR script after assigning default values.

The configuration file on the client may need to be edited to instruct the client about how to reach and login to one or more servers. Client-setup attempts to populate the first entry with reasonable values.

Most users will never need to alter the configuration file on the server.

Security Note: Keep the permissions of the configuration file secure. If you do not, you have handed root-access to others.

Rules for Editing

  • The file is case-sensitive!
  • There must be no spaces on either side of the “=” or the assignment will fail. This is because the file is a shell “sh” script.

Client Server Assignments

One or more fields must be populated for each server to be polled. Any unpopulated values are pre-populated with defaults.

Replace <Num> with the sequential numbers. The number must be sequential starting from 1.

Server<Num>Host=<hostname | IP address>

Server<Num>User=<login username>

Server<Num>Password=<login password>

Server<Num>Port=<SSH port to connect to>








  • client, runs as a service, after network up and periodically


  • a link to iar
  • runs when an iar request is made via ssh
  • when in slave mode it passes requests (and data), with caching, from master to clients


  • it is an NSS provider
  • extends NSS(glibc) to include the IAR replicated credentials (functionally it feeds retrieved account information into passwd, group, shadow)

File System Layout

  • Configuration file: /etc/iar/config
  • Master Server account data: /etc/iar/master/
  • Slave Server account data is passed through: /var/lib/iar/server/
  • IAR client data is temporarily stashed in: /tmp/_iar/ then recorded in: /var/lib/iar/client/
  • The NSS plug-in reads the data in: /var/lib/iar/client/


iar [-h|--help|help]  |  [
           servermode master|slave
           approve-subnet <CIDR>
           adduser <username>
           deluser <username>
           passwd <username>
           lock <username>
           unlock <username>
           lockpasswd <username>
           unlockpasswd <username>
           addgroup <groupname>
           delgroup <groupname>



Displays the program’s status.

Shows if ‘client’ or ‘server’ mode.

If client:
  • Shows name of server used and the time of last successful sync.
  • Shows power state information used by dynamic polling.
If server:
  • Shows if running the server.
  • Shows if master or slave.
  • Shows approved and pending clients.


Retrieves account information from the iar-server.

This is the command to use for testing.


Like the ‘client’ command, but reduces the server polling interval on laptops when the:
  • ACPI power adaptor is detected;
  • Power adaptor reports “off-line”; and
  • ACPI battery provides power information

Then, the polling interval is adjusted based-upon the battery capacity.

Battery Level:

<=10% : Skip invoking client poll

11 - 19% : Invoke client poll once every 90 minutes

20 - 50% : Invoke client poll once every 60 minutes

51 - 100% : Invoke client poll once every 20 minutes

This is what the cron job invokes.


  1. Checks/adds the magic lines to /etc/passwd, /etc/group, and /etc/shadow to enable NSS integration.
  2. Installs the ‘iar’ NSS module into: /etc/nsswitch.conf
  3. Sets up upstart init, or rc.d and cron jobs from synchronization.


master mode
Serves account information to clients from /etc/iar/
slave mode
Serves account information from /var/lib/iar/


Add user account for _iar

servermode master|slave

Selects between serving data in master mode or slave mode.


Approve pending client hosts, interactively.

approve-subnet <CIDR>

Approve all client connections from an IP address that is within range of the given subnet mask, in CIDR form.

i.e. approve-subnet

would automatically approve any client from through

This function is specifically intended for virtualation and other special uses. It is UNSAFE and illadvised for general use.

Subnet masks are accumulated in IAR configuration variable, ApprovedSubnets, separated by spaces.

adduser <username>

Add a user account

deluser <username>

Delete a user account

passwd <username>

Change a user account’s password

lock <username>

Lock a user account

unlock <username>

Unlock a user account

lockpasswd <username>

Lock a user account from password login (Keypair login remains enabled.)

unlockpasswd <username>

Unlock a user account for password login

addgroup <groupname>

Add a group

delgroup <groupname>

Delete a group


Removes all client and/or server hooks which are required for operation (Configuration files and logs are preserved.)


Performs a remove then deletes all configuration files and logs

Installing from Source

IAR leverages the GNU Autotools system for builds. For most systems you should be able to:

tar xvf iar-VERSION.tar.gz
cd iar-VERSION
./configure --help
make check
sudo make install

./configure --help shows the available options for installing, in particular

./configure --prefix=/usr

This will install files to the /usr system tree, overriding the default of /usr/local.

If something goes wrong, or there are special requirements involved, the system includes the Autotools bootstrap code. Any changes to or should be followed by



Start Algorithm

  1. Exit if other copies of iar client are running.
  2. Check if /etc/iar/config is secure, and attempt to secure if not. Abort if it cannot secure.
  3. Reads configuration from /etc/iar/config
  4. If no site-key is found, generate a random one, and attempt to store in /etc/iar/config
  5. Attempt to make /tmp/_iar/
  6. Attempt to set permissions.
  7. Check permissions.

Client Algorithm

  1. If the mode is server-master, set data-destination to “/etc/iar/master/” else set data-destination to “/var/lib/iar/server/”

  2. Retrieve the public key from the config file.

  3. Mark the public key as ‘trusted’.

  4. For each server hostname in /etc/iar/config (i.e. Server1Hostname=””):

    1. Set sync destination to “/tmp/_iar/transfer/[server hostname:<port>]/” if writable, else set destination to “/var/lib/iar/transfer/[server hostname:<port>]/”
    2. ssh to hostname ignoring host-keys, send query data on command-line. #. untar files to sync destination. [passwd group shadow gshadow TimeStamp HashDigest HashDigest.signed] #. Verify HashDigest signature, if not successful, delete transfer. #. Verify auth files against HashDigest, if not successful, delete transfer.
  5. Determine newest file-set version which is not newer than current ms since epoch.

  6. Copy files (passwd group shadow gshadow TimeStamp HashDigest HashDigest.signed) from selected file-set to “/var/lib/iar/client/”

Server Algorithm

  1. Acquire lock.

  2. Ensure we have files to serve.

  3. If in master mode:

    1. If needed, generate a key-pair and store in config-file
    2. Set datapath to “/etc/iar/master/”, else slave mode, datapath “/var/lib/iar/”
  4. Calculate checksum of the current version of the data-files.

  5. Exit if hashes match.

  6. If in master mode:

    1. Generate tar (passwd group shadow gshadow TimeStamp HashDigest HashDigest.signed).
    2. Retrieve key-pair from config file.
    3. Sign transfer file using GPG.
  7. Send signed transfer file.


The IAR application attempts to keep external dependencies to a minimum, but there are a small few.


IAR server relies on ‘nixhash’, for encrypting password entries.

It is not required for Debian-based systems, but it can be used inplace of the ‘whois’ package on embedded systems.

Built with Autotools, there is nixhash.c, nixhash.h with a dependency on -lcrypt.

nixhash is available from the IAR distribution source.


IAR uses ‘sshpass’ to allow clients to connect with an IAR server, without need of shared keys.

sshpass is an external dependency.

Status Return Codes

  • 0 OK
  • 1 Invalid commands and general permission problems.
  • 2 Dropped connection due to unsupported protocol version.
  • 3 GPG signing key in response data from server could not be trusted.
  • 4 GPG server public keyring missing or empty in response data from the server.
  • 5 Permission problem when replicating authentication.
  • 6 Missing files when replicating authentication.
  • 100 Obviously dangerous recursive remove was blocked.
  • 101 Shred command, safety net during cleanup of transfer files.


Most of the IAR testing is manual. sudo or root privilege is required for most IAR operations, as there are confidential authentication files and shared keys involved.

Client Initialization

(This section is in need of update to reflect using the iar “purge” and “remove” commands.)

Ensure there is the most recent copy of iar available.

Some of this testing can be influenced by what files are on the server as well.

  • Clean-out the configuration file /etc/iar/iar.conf

    rm /etc/iar/iar.conf
  • Clean-out any transfer files that may have accumulated

    sudo rm -r /tmp/_iar/
  • Clean-out any existing authentication files

    sudo rm -r /var/lib/iar/
  • Generate a clean configuration file, edit /etc/iar/iar.conf

This will use a default user account and password.

  • Then kick an initial test with

    sudo ./iar client


The main IAR script, iar is commented with ROBODoc comment blocks. API documentation generated with

List robobash.rc, and fill in the proper command line

(cd .. ; robodoc --rc docs/robobash.rc)

    --src ./
    --doc ./docs/robodoc/
    --masterindex "Master index,index"
    --tabsize 4

ignore files:

accept files:

The IAR application bundle is documented with ReStructuredText and Sphinx.

make singlehtml


To Invoke sshd for _iar Only User Login

Requires creation of a server key pair for the sshd for the _iar account:

Command: ssh-keygen -f /home/_iar/ssh_host_rsa_key -N '' -t rsa -b8192

Command: /usr/sbin/sshd -oPort=22322 -oAllowUsers=_iar -oHostKey=/home/_iar/ssh_host_rsa_key

Debian Package Building

Make source and binary deb packages with:

make deb

Clean with:

make clean

Debian Control Creation

(You don’t need to do this, it only needed to be done once.)

dh_make -p iar_123.45 --native --email <e-mail address>

RPM Package Building

Make source and binary rpm packages with:

make rpm

Clean with:

make clean

NSS Advanced Information

Check for the NSS module in library path:
ldconfig -p | grep iar
Rebuild library cache (necessary after adding or removing any library):