One of the ways the server can control who has access, is through the use of a private authentication file, or AuthFile. The file consists of plain text lines, each specifying a username, password, and other options. An AuthFile is also the preferred method to enable Anonymous Access.
A sample AuthFile, named svpasswd, is included in the "Server Files" folder.
Step-by-step instructions for enabling Private Authentication can be found in the Adding Users section.
An AuthFile is activated by specifying its path with the AuthFile configuration variable or the "-A <password-file>" command line option. The recommended location in Windows is "%SYSTEMROOT%". An "Install svpasswd.bat" script is included which will copy the example svpasswd.txt file into that location after you are done editing it. For unix systems, "/etc" or "/usr/local/etc" are recommended locations.
Specifying an AuthFile will change the default setting of SysAuth to disabled. If you require system authentication, be sure to explicitly enable it before enabling an AuthFile.
The contents of the file must be ASCII or UTF-8 with no BOM. Windows systems may use LF or CRLF line delimiters, while all other systems should use LF. Each line must be no more than 2047 bytes in length and consists of the following colon separated fields:
Username : Password : UserId : GroupId : HomeDir : Options
|Username||Up to 31 characters that will be matched against the username given by the client. It is best to avoid special characters and spaces. The first match will be used and a username found here will override any listing in the system database. When attempting to match an Active Directory user with an explicit domains, use the syntax user@domain.|
|Password||The plain or hashed text that the client's password must match. Password hashes can be generated using mkpasswd and are recommended for security. Plain text passwords must not be 13, 32, or 80 characters in length as those strings will be interpreted as hashes. A single * character in this field will activate Shadow Authentication.|
|UserId||If you specify a system user id number here, then all accesses matching Username will be performed with the privileges of this user id. Note that servedat must be started as root to set user ids. The value -1 is not valid on most systems and will be mapped to INT_MAX or UNINT_MAX. This field is ignored on Windows and when Shadow Authentication is used.|
|GroupId||If you specify a system group id number here, then all accesses matching Username will be performed with the privileges of this group id. Note that servedat must be started as root or as a user belonging to the given group id. The value -1 is not valid on most systems and will be mapped to INT_MAX or UNINT_MAX. This field is ignored on Windows and when Shadow Authentication is used.|
|HomeDir||You may specify a Home Directory for the Username. Leave this blank to use servedat's default home directory or to refer to the system record when Shadow Authentication is used. As a special case, the Windows version will allow volume labels like "D:\path", even though this use of a colon violates the field delimiting.|
|Options||This is a comma separated list of additional per-user options. Options followed by an equals sign require a value as described. Also see Access Privileges for server-wide access controls.|
|AdminOnly||Prohibits all actions except adminstrative functions. Only operations with an action code starting with *r are permitted.|
|AdminReport||Enables access to transaction reports for this user. It is recommend that you create user credentials specifically for retrieving reports, especially if it is to be done programmatically.|
|File Access Restrictions|
|ReadOnly||Prohibits any actions which would change the filesystem.|
|GetOnly||Permits only individual file downloads (with or without compression). All other actions, including directory listings, are forbidden. Useful for providing users with targeted downloads via expedat:// URLs. Not compatible with SyncDat.|
|WriteOnly||Allows only file uploading and related actions. Files cannot be downloaded and directories cannot be listed. This may be useful in creating drop-boxes to be shared amongst semi-trusted users. Not compatible with SyncDat.|
|WriteListOnly||Allows only directory listings, file uploading, and related actions. Files cannot be downloaded. Similar to WriteOnly except that users can see what files are already on the server.|
|If more than one of ReadOnly, GetOnly, WriteOnly, or WriteListOnly is enabled for a user, either due to individual or server-wide settings, then the most restrictive intersection of them will be enforced. This can result in a user having effectively no privileges.|
|NoOverwrite||Prevents incoming files from overwriting existing files. An existing file must be deleted prior to uploading one with the same name.|
|ObjectOnly||Prevents direct access to the filesystem: all transactions must declare a valid Object Handler.|
|RestrictHome||Prohibits access to files outside of the home directory, with two exceptions. Folders declared by AllowPath can be accessed as absolute pathnames. On non-Windows systems, symbolic links will be honored with some limitations. RestrictHome is always enabled for the ANONYMOUS user, even if it is not specified here.|
|Values override global and SiteOptions where applicable.|
|Aggression=||Sets the default MTP/IP aggression level. See Aggression for details.|
|AggressionLimit=||Sets the maximum Aggression value which clients may select. See AggressionLimit for details.|
|Capacity=||This user will be limited to given number of simultaneous operations. For example, Capacity=1 would limit the user to one file transfer at a time. Incidental operations such as deleting a file or listing a directory are not counted in this limit. High overhead operations such as scanning a directory tree or any call to an object handler do count toward this limit.|
|Sets a default speed limit for individual uploads and/or downloads. See MaxRate for details. MaxRate takes a single value which is applied to both MaxRateIn and MaxRateOut.|
|Sets a hard speed limit for individual uploads and/or downloads. See MaxRateLimit for details. MaxRateLimit takes a single value which is applied to both MaxRateLimitIn and MaxRateLimitOut.|
|RestrictClients=||The user may only access the server from the given client host. The client may be specified as a DNS host name, IP address, or subnet in the form of address/bits. A DNS name will be resolved at startup and refreshed approximately every twelve hours.|
See the enclosed svpasswd sample file for an example of formatting. Note that servedat will not start if it is unable to parse the private authentication file. For the best security, be sure to locate this file outside of the default home directory, set its permissions so that access is restricted to trusted users, and use mkpasswd to generate password hashes instead of using plain-text.
If the password field consists of a single * character, then the system authentication database will used to authenticate the password. The UserId and GroupId fields will be ignored and the corresponding values set from the system database. If the HomeDir field is blank, then the home directory will be calculated as for a system user home.
When matching Active Directory users with explicit domains, use the syntax user@domain for the user field. If Active Directory may allow a user to authenticate with both user and user@domain, or with multiple domains, you must create a separate record for each.
If SysAuth is 0 but at least one Shadow Authentication record exists, then the system database will be queried only for shadow records in AuthFile. System users not in AuthFile will be denied access unless SysAuth is set to 1.
If a username in the AuthFile matches that of a system user and a password or hash is given in the AuthFile record, then no system lookup will be performed and the AuthFile record will be used in place of the system settings.
The AuthFile is loaded at startup and may be modified while the server is running. Modifications will be loaded a few minutes after any change. An automatic reload does not effect transactions already in process, but changes will apply to any new transactions. Clients performing a series of actions, such as multiple transfers or one-at-a-time folder copies, will be disrupted if the reload invalidates their credentials. Automatic reload is controlled by the AuthReload configuration variable, which specifies how many minutes servedat should wait after detecting a change. A value of 0 disables automatic reload.
To avoid any chance of file corruption, you should edit a copy of the AuthFile and move that into place once your editing is complete.
You can also manually reload the AuthFile by restarting servedat. On unix systems, sending the HUP signal to a running servedat process will cause it to restart and reload all of its configuration settings. On Windows systems with servedat in service mode, the service manager can be used to stop and restart servedat. Any active transactions will be interrupted by a restart.
On unix-like systems, each AuthFile user will operate with the user and group id specified. This will allow authenticated access on NFS filesystems. Other network attached storage, such as CIFS or AFP, may deny access to AuthFile users if they are configured to require authentication. See Tech Note 0031 for more about NAS authentication.
On Windows, each AuthFile user will operate with the privileges of servedat itself. It is therefore important to make use of options such as RestrictHome for Windows AuthFile users. Network attached storage may deny access to AuthFile users if it has been configured to require its own authentication. See Tech Note 0031 for more about NAS authentication.