Authentication File
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.
Examples
Following are some records taken from the included "svpasswd" example file:
# Password may be cleartext, access may be limited johnny:apples:100:100:/home/johnny:ReadOnly # Use mkpasswd to generate SHA-2 hashes for better security joey:3df7708aff9183f23338…cd8751b971768b6eaa0:101:101:/home/joey:ReadOnly # Shadow Authentication retrieves the password and uid/gid from SysAuth ccabbot:*:::/Volumes/Data/ccabbot:RestrictHome,GetOnly # Only allow access to select object handlers s3user:99:99::ObjectOnly=S3|trc
Syntax
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 | This string will be matched against the username given by the client. It must be less than 64 bytes when UTF-8 encoded and should consist of only ASCII letters, numbers, and printable symbols. The use of other characters, such as extended unicode characters, may work in some environments but is not assured and may compromise security. 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. This field is case-sensitive |
| Password | The plain or hashed text that the client's password must match. Supported formats are determined by the AuthHashes option and may include plain, crypt, md5, or sha256. Password hashes can be generated using mkpasswd and are recommended for security. Plain text passwords must be less than 64 bytes when UTF-8 encoded and should consist of only ASCII letters, numbers, and printable symbols except colon. Password strings which are exactly 13, 32, or 80 bytes in length will be interpreted as hashes if crypt, md5, or sha256 hashes are enabled respectively. Disabling crypt and md5 via AuthHashes is recommended and support for these hashes may be removed in the future. A single * character in this field will activate Shadow Authentication. This field is case-sensitive. |
| 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. This field should be treated as case-sensitive, although some filesystems may accept case variants under some conditions. |
| 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. This field is not case-sensitive. |
| Administrative Rights | |
| AdminOnly | Prohibits all actions except administrative 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. |
| Access Restrictions | |
| Disabled | Any action by this user will receive an "Access Denied" error. Up to 63 bytes of text (letters, numbers, and spaces only) may be given to provide further explanation to the client. For example, "Disabled=Your account has been disabled". |
| Expire= | The user will be disabled near the time given as YYYYMMDDHHMM UTC. The time may be followed "+" and up to 63 bytes of text (letters, numbers, and spaces only) to provide further explanation to the client. For example, the following will expire on April 15, 2022: "Expire=202204150000+Your account has expired". |
| ReadOnly | Prohibits any actions which would change the filesystem. Optional "=0" argument will override global ReadOnly restriction for this user. |
| 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. Optional "=0" argument will override global GetOnly restriction for this user. |
| 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. Optional "=0" argument will override global WriteOnly restriction for this user. |
| 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. Optional "=0" argument will override global WriteListOnly restriction for this user. |
| 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. Optional "=0" argument will override global NoOverwrite restriction for this user. |
| ObjectOnly | Determines which storage mechanisms the user is allowed to access. 0: Overrides the global ObjectOnly option to allow access to all storage types. 1: Blocks access to the filesystem, allows all object handlers. <list>: A list of permitted object handler action codes. Any code not listed will be denied. The special code "*files" will permit access to the filesystem in addition to any other listed handlers. Handlers in the list must be separated by the | character with no spaces. For example, "ObjectOnly=*files|S3ohio" would allow access to the filesystem and "S3ohio" handler, but not any other handlers. |
| 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. Optional "=0" argument will override global RestrictHome restriction for this user. RestrictHome is always enabled for the ANONYMOUS user, even if it is not specified here. |
| Network Restrictions | |
| 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 the 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. |
| MaxRate= MaxRateIn= MaxRateOut= | 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. |
| MaxRateLimit= MaxRateLimitIn= MaxRateLimitOut= | 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. |
Lines beginning with a # character are ignored and may be used for comments. Comments may also be placed at the end of a record line by using a # character.
See the sample svpasswd file in the "Server Files" folder for an example of formatting. Note that servedat may 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.
Shadow Authentication
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. Note that the entire field, including the domain part, is case-sensitive.
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.
Automatic Reload
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.
Privilege Details
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 SMB 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.