Adding Users

When you are installing the servedat server in a production environment, you will probably want to configure, or at least verify, the user authentication settings.

If you simply run an "Install Servedat" script without any other setup, the server will default to System Authentication (SysAuth). This will permit users who have logon accounts to the server operating system to access the ExpeDat server. Use the same username and password that you would use to logon to the server console. With System Authentication, you add and manage users with the operating system's own user management tools.

It is best to not rely on the default authentication settings, because future updates to your configuration could result in unexpected changes. Explicitly set SysAuth as described below.

User credentials may be also be specified in a private Authentication File. A private authentication file stores credentials that only ExpeDat will use and is required if you want to enable anonymous access or setup a transaction reporting account. More advanced installations may wish to create a custom Authentication Handler.

The following step-by-step instructions walk you through the process of setting up basic SysAuth and/or AuthFile authentication. Read all the way through to the end to make sure you do not miss any important steps, such as installing the updated files.

Summary of Steps

Edit servedat.cf to enable SysAuth and/or AuthFile.
Edit svpasswd if AuthFile is enabled.
Install servedat.cf, and svpasswd if AuthFile is enabled.
Restart the server.

Extract the Distribution Package

For zip or tgz packages, extract the contents to a local hard drive.

For a dmg disk image, copy the "Server Files" folder to a local hard drive (such as your Desktop).

Editing the Configuration File

Look in the "Server Files" folder of the ExpeDat distribution package. There you will find a file called "servedat.cf". This file contains all of the setup options for the server. Unix users may be familiar with configuration files and their syntax. The Configuration File and Options chapters have complete details, but the steps below will get you through the basics.

Open this file in any text editor, such as NotePad or TextEdit.

# Sample servedat configuration file, updated 2016/01/07 # See the documentation for install location and precedence. # ...

Alternatively, you can edit or create servedat.cf files using DEI's secure online servedat.cf editor:

https://ssl.dataexpedition.com/configure/servedat-cf.php

After using the online editor, download the new configuration file into your "Server Files" folder prior to running "Install Config" in the second-to-last step below.

Setting System Authentication

To enable ExpeDat access for all system users, follow these steps. To only enable access for individual system users, or to create ExpeDat only usernames, skip to Setting Private Authentication.

Open the configuration file, or start the servedat.cf editor, as described above. Scroll down near the bottom to the line containing "SysAuth":

#SysAuth 0 # 0 or 1 # Set to 1 to use the system user database. This is the default when running # as a service. Anonymous access will be prohibited unless an ANONYMOUS # entry is given in AuthFile.

If you wish users who already have the ability to logon to the server machine to use the same credentials for accessing ExpeDat, then uncomment the SysAuth line (remove the hash or enable the checkbox) and change the 0 to 1.

SysAuth 1 # 0 or 1 # Set to 1 to use the system user database. This is the default when running # as a service. Anonymous access will be prohibited unless an ANONYMOUS # entry is given in AuthFile.

If you prefer to manage users exclusively using the private authentication file, then set the value to 0 instead.

By default, system users will be directed to their system home/profile directory. You may specify an alternate home directory for system users with the SysHome option. To redirect all system users to an alternate set of home directories, scroll down to "SysHome", remove the hash or enable the checkbox, and enter the absolute pathname of the alternate home folder. For example:

SysHome E:\expedatusers\ # Pathname # Override the usual home folder for system users and instead redirect # them to a subfolder of the given path. The subfolder must have the # exact username and its permissions must be set to allow the user access. # When combined with RestrictHome, system users will not be allowed access # outside of this folder.

When SysHome is set to a path, that folder must contain subfolders with the names of all system users and each must have permissions giving its user access. See the Home Directories chapter for more about home directories.

To instead redirect all system users to a single shared folder, set HomeDir to point to that folder and set SysHome to 1.

SysHome 1 HomeDir E:\commonfolder\

Don't forget to save your changes!

Setting Private Authentication

To enable and or control access for individual system users, create ExpeDat only usernames, or enable anonymous access, follow these steps. To enable access for all system users, go back to Setting System Authentication above.

Scroll to near the top of the configuration options, where you will find the line containing "AuthFile":

#AuthFile %SystemRoot%\svpasswd.txt # Pathname # Specify an authentication file. See svpasswd example. Anonymous access # will be disabled unless an ANONYMOUS user entry is present. # Default: None

If you wish to store some or all user records in a private file, then uncomment the AuthFile line (remove the hash or enable the checkbox). The server will then expect to find a password file at the given path location.

If you enable AuthFile without also enabling SysAuth, then system authentication will be disabled by default! The server always chooses the most restrictive default that still allows some access.

Don't forget to save your changes!

Editing svpasswd

If you have enabled AuthFile above, then you will need to create or a edit a private authentication file. Otherwise you can skip to "Installing Files" below.

Look in the "Server Files" folder of the ExpeDat distribution package. There you will find a file called svpasswd or svpasswd.txt. Open this file in any text editor, such as NotePad or TextEdit.

# Sample servedat authentication file # If SysAuth is also in use, this file will be checked first. # Lines beginning with a hash-mark, space, or tab are ignored. # # Username : Password : UserId : GroupId : HomeDir : Options # ...

The format of this file is similar to that of a unix passwd file. Full documentation can be found in the AuthFile chapter. The following steps will walk you through the basics.

If you wish to allow clients to access your server using no username or password ("anonymous" or "public" access), then uncomment the ANONYMOUS line (remove the hash) and change the home path to the location of your public files:

# ANONYMOUS will match requests which offer no username ANONYMOUS::::C:\Documents and Settings\All Users:ReadOnly,RestrictHome

The line above will allow any ExpeDat client to download files from the given path. The ReadOnly option prevents uploading. The RestrictHome option prevents this account from accessing any files outside of this folder.

To setup an account with a username and password, uncomment one of the other example lines (remove the hash mark) and edit the fields:

joey:3df77...b6eaa0:::C:\Documents and Settings\joey:RestrictHome

The first field is the username. This is case sensitive and must be less than 64 bytes when UTF-8 encoded.

The second field (after the colon) determines how the password will be handled. It can be a single asterisk *, a plain-text password, or an SHA-256 hash.

A single asterisk * character creates a Shadow Authentication record. The username will be looked up in the system authentication database and the user identity will be retrieved from there if the password given matches the system password. This is useful to control system user access options on an individual basis.

A plain-text password is the simplest way to establish a private authentication method. The password must be less than 64 bytes when UTF-8 encoded should consist of only letters, numbers, and printable symbols except colon. This is useful for creating credentials that can only be used with ExpeDat. However, hashing the password is much more secure.

To create a secure password hash, use the "mkpasswd" utility included in the "Server Files" folder of the ExpeDat package.

Enter a password to be hashed: AuthFile SHA-256 hash: 3df7708aff9183f233b5523369cf7d1ac3e850806b9b2d91b02b6e5a22738cd8751b971768b6eaa0 The hash has been copied to the clipboard.

When running mkpasswd from a Windows or macOS console login, the hash will be placed in the clipboard so you can immediately paste it into the AuthFile. If you are running mkpasswd remotely, such as via ssh, make sure that you select all 80 characters when copying it.

On unix systems, the next two fields are used to set a user and group id for this user. (Those fields are ignored in Windows.) You may wish to set these to match a system user who owns or will be managing these files. To find the user id and primary group id of a user, login as that user and type "id" on the command line. For example:

macosx-1: id uid=501(macuser) gid=20(staff) groups=20(staff),80(admin)

The fifth field specifies the path to this user's Home Directory. Make sure that the folder exists and that it is accessible by the user id. If this is a shadow user (password is *), then leave this field blank to retrieve the system home directory for this username.

The last field specifies user options, such as the access restrictions shown above. These restrictions are applied in addition to any system-wide restrictions.

Add a new line for each user account you wish to create.

Don't forget to save your changes!

Installing Files

After you have edited servedat.cf and svpasswd, make copies and store them outside of the ExpeDat install folder. When you update your software in the future, you may want to copy those edited files back into the new installation folder.

On Windows systems, right click on "Install Config" and select "Run as Administrator", then do the same for "Install AuthFile". This will copy each file into its default system location.

On macOS systems, right click on "install-config" and select "Open". You may be prompted to enter your administrative password. You may be asked to confirm that you wish to overwrite existing configuration files and restart the server. If you have not yet installed the server, answer 'n' to the restart prompt and proceed to the next step.

On all other systems, copy servedat.cf and svpasswd into /etc/.

(Re)Starting the Server

If you have not yet installed the server, do so now by running the "Install Servedat" script. If you are running Windows you must right click on the script and select "Run as Administrator".

If the server is already running, you may run the installer script again to restart it and load the new configuration files. This will also re-install the version of servedat in the current "Server Files" folder. That may not be desirable if the versions do not match.

Restarting the server will terminate any transactions currently in progress. By default, clients will automatically resume after about one minute.

On Windows systems, you may also reload the configuration by using the "Services" administrative tool to restart the "ServeDat" service.

On macOS systems, you may restart servedat using the Terminal command:

sudo launchctl stop com.dataexpedition.servedat

The system should then immediately restart servedat.

On Unix systems, including macOS, you may reload the configuration by sending the HUP signal to the servedat process. On most systems, this can be accomplished by typing "sudo killall -HUP servedat".

Once the configuration has been updated, changes to AuthFile will automatically reload a few minutes after they are saved, depending on the AuthReload option.

More Information

For much more detailed information about managing the ExpeDat server, please read the servedat Server chapters. For more general instructions about updating the server configuration, see the Configuration File section.

For advanced technical information, refer to the online Tech Notes.