Using ncftpd_passwd

The ncftpd_passwd utility program is used to create and modify NcFTPd Password Databases.  These databases are not regular text files like /etc/passwd, so a separate program is needed to manage them. The reason the files are in a binary format instead of human-readable format is because one of the advantages of using a file other than /etc/passwd is for performance -- an indexed database file is very efficient to read, while the /etc/passwd file must be scanned sequentially.  A database file can handle a large number of users without any noticeable performance degradation.

After a database has been created, you must configure the domain so that NcFTPd uses your database in place of (or in addition to) /etc/passwd. See the option passwd for details. You will need to restart NcFTPd if you change the domain's passwd option, but you do not need to restart whenever you modify the database file.

  1. Working with password databases
  2. Additional Fields for Password Database Records (that aren't in /etc/passwd)
  3. Tips
  4. Advanced options

Working with password databases

The files themselves should be owned by root and have mode 0600 (no read or write permission for group nor public).  This is recommended because the databases contain the encrypted password.  Having the encrypted password publicly available can be a security risk, which is why most modern UNIX systems have moved the encrypted passwords out of the /etc/passwd file into a separate file (often called the shadow password file).
Creating and removing databases
To create a database you simply use the utility with the add user operation described below.  The database file will be created for you automatically if it did not exist.  To delete a database, you can simply remove it with /bin/rm.
Record format
The user entries are identical to the lines in the /etc/passwd file with one exception: the group field is a comma-delimited list of group IDs.  Therefore, the records look like this: Example: This user has user ID 500, home directory of /home/mgleason, primary group ID of 600, and membership in supplementary group IDs 700, 701, and 702.


Adding users
To add a user, run the program specifying the database file with the -f flag, and the complete user record specified by the -a flag.  Since the user record may have whitespace in it, use your shell's quote characters appropriately.

Example 1:  Add the mgleason user above, into a database named /usr/local/etc/ncftpd/pwdb/passwd.db.

It is inconvenient to use some other program to create the encrypted password based off of the cleartext password, so you can use the -c flag to tell the utility to encrypt the contents of the password field for you before adding the record.

Example 2:  Add the mgleason user above, setting the password to secret.

If you want to create a user whose user ID is identical to an existing user in the /etc/passwd file, you may use that user's name instead of manually look up the user ID. Similarly, you may substitute group names for group IDs and the utility will look them up for you.

Example 3:  Add the mgleason user above, with user and group name replacement.

If you would prefer to input each field interactively (rather than constructing the colon-delimited record), you can (with version 2.8.6 or later) invoke ncftpd_passwd with the -A flag, like this:

Changing users
Modifying a user entry is the same as adding a new one, except you need to use the update flag (-u), instead of the add flag (-a).

Example: Change the password for mgleason to myxlplxx (using the -c flag also).

If you would prefer to edit each field interactively (rather than querying and modifying the colon-delimited record), you can (with version 2.8.6 or later) invoke ncftpd_passwd with the -U flag along with the user to edit, like this:

Changing passwords
While the update flag lets you change an entire record, often all that is desired is to change the password field of the record.  You can do this by using the -p flag to specify a user record, and then ncftpd_passwd will prompt you for a new password.  You can also use the -P flag to specify the encrypted password directly, if you happen to have it.

This flag can also be used by a non-superuser to change their own password entry.  This requires some special setup, as described in the section on advanced options below.

Example 1: Change the password for mgleason to myxlplxx

Example 2: Change the encrypted password for mgleason:
Querying users
To print the record for a user, specify the user name with the -Q flag along with the database.

Example: Query mgleason's record.

Deleting users
To remove a user's record, specify the user name with the -d flag along with the database.

Example:  Delete mgleason's record.

Printing the entire database
You may use the export flag (-x) to convert a database into a textual format.

Example:  Dump the entire passwd.db database.

Importing records
You can add records in batch mode by creating an import file and using the import flag (-i).  You can also use the -c flag and user name and group name replacement when you import the records.


Importing the /etc/passwd file
You may elect to not use the /etc/passwd at all in favor of using just password databases, but you may want to load all the users from it into a database.  When you use the special -I flag, the /etc/passwd file is imported.  The special treatment is that the encrypted passwords are taken from the shadow password file (if needed), and the group field is created from the /etc/group file.


Additional Fields for Password Database Records (that aren't in /etc/passwd)

NcFTPd uses a superset of the /etc/passwd format for user records, by adding additional fields after the shell field.

Here's an example that shows one record in /etc/passwd format and a second record which takes advantage of the additional fields:

The complete list of fields is then:

Fields 5 (full name) and 7 (shell) are not used by NcFTPd and may be left blank. Older versions of NcFTPd required a valid shell field even though it was never used.

Fields 8, 9, 10, 11, 13, 14 are used for NcFTPd Quotas and are described in more detail there, but to enable those features you can simply use ncftpd_passwd with a record formatted similarly to the m2gleason record above. Quota fields do not take effect with a value of 0 or if they are empty.

Field 12 was formerly reserved for future use as a quota options field. This field is now a general "catch all" field for some extra variables (in a similar vein to how the full name field was extended to include GECOS information). The variables are comma-delimited option=value pairs. The following variables are defined:


Advanced Options

There are four modes of operation which NcFTPd and ncftpd_passwd operate in regards to password databases.  In the standard mode, the Superuser runs ncftpd_passwd (note:  not a regular user running ncftpd_passwd with setuid-root) and password databases are owned by root and of mode 0600.

The second mode (call it Mode 2) is where the system administrator decides to let a regular user own and maintain the password database, and the administrator configures a domain in NcFTPd's file to use this file as a password database.  In this mode, NcFTPd ignores the user ID and group ID fields in the password database, but instead all users in the database are treated as equivalent to the regular user that owns the password database.

The third mode (Mode 3) is where the system administrator changes ncftpd_passwd so that it is owned by root and enables the "setuid-bit".  The password databases are owned by root and mode 0600, but ncftpd_passwd can be run by a regular user to create user accounts with the same privileges of his own.  For this mode to work, the administrator must create a file called /etc/ftp.passwd.conf which contains a list of files that users may modify using ncftpd_passwd.

The fourth mode (Mode 4) is intended to be used by CGI programs. Like Mode 3, ncftpd_passwd is setuid-root, but unlike Mode 3, it can modify any and all accounts in the database, as well as add accounts with any privileges.

Setting up Mode 2

To use Mode 2, you simply set the password database name in the file, and let the user run ncftpd_passwd to create users. Create the database with their first user, and make sure the database file is owned by the user you want to maintain it. You may want to create a shell script for them that simplifies use of the the program.  For example, it is easy to forget to include the -f flag and the password database so you might have your script hard-code that inside the script.

Internet Service Providers often have a regular user own their own virtual domain, and in this case it makes sense to allow the domain owner to maintain the database of users that access this domain.  However, you must remember that there's nothing to stop a malicious user from trying to exploit your system, because any users created have identical privileges.  For example, a malicious user may create a user whose home directory is "/" which would give the user access to files and directories which his user privileges allow, such as read access to /usr/bin and /etc/passwd. It is up to you to properly restrict who runs ncftpd_passwd and what input is sent to it.

Setting up Mode 3

Using Mode 3 requires a special file to be created by the system administrator, the /etc/ftp.passwd.conf file.  This file contains the files that regular users running ncftpd_passwd are allowed to modify.  Each line in the (plain text) file should be the absolute pathname of a password database file followed by a space, followed by a comma-delimited list of users that are allowed to modify this database.  You may use the keyword ALL in place of a user list to denote that any user may modify the database.  In addition, a line can be commented-out by having the first character be a # character.

An example /etc/ftp.passwd.conf file:

You would then make a setuid-root copy ncftpd_passwd and have it so only the users you wish to run the program are able to do so. The example below shows how to do this, but letting all users run the program, since the program is set to be publicly executable. You may wish to create a group in /etc/group and use group permissions to restrict access.

Finally, the /etc/ftp.passwd.conf file must be owned by root and mode 0600.

Setting up Mode 4

Using Mode 4 also requires the /etc/ftp.passwd.conf file. The difference is that the list of users includes the special token allow-setuid-root. Example:

Next, make a copy of ncftpd_passwd which is setuid to root and setgid to the web server user. This example assumes that the web server user is named web and is the only member of a group named web:

You could then create a CGI program that would run this copy of ncftpd_passwd. It is up to you to secure this script so that only administrators can run it; for example, you might put it behind an SSL-enabled server and then have your CGI program prompt for a password. If you don't do that, anyone who knows the URL to your CGI can fully manipulate the password database!

Remember, it is up to your CGI program to restrict what input is sent to ncftpd_passwd. For example, you would probably want to ensure that users cannot be created with a privileged UID, or have a home directory of "/" unless you really want to do that.

 NcFTPd Home