Configuring the Default lukemftpd FTP Server

Configuring the Default `lukemftpd` FTP Server

The default Mac OS X FTP server allows you to customize its configuration.

`lukemftpd` FTP Server Options

You've just turned on your FTP server. If you looked at the /etc/xinetd.d/ftp file, you noticed that the server runs by default with the -l option ( server_args = -l ), which is the option that forces the logging of successful and unsuccessful FTP sessions.

If you study your FTP connections to keep track of what sorts of malicious individuals are trying to crack your security, you might want to consider logging additional information. The lukemftpd server options (shown in Table 12.1) include a number of settings to control the different types of information stored and the way that it is stored. To implement any of the options, edit the server args entry in /etc/xinetd.d/ftp to reflect the options you want to use. Then run killall -HUP xinetd to have xinetd reread its configuration. Alternatively, if you are using inetd instead, edit the ftp entry in /etc/inetd.conf to include the desired server arguments and have inetd reread its configuration file.

Please note that whenever you turn the FTP service on or off via the System Preferences pane, any other configuration changes you have made to the service are retained, rather than being reset. Nonetheless, it is a good idea to keep a copy of the file with your configuration changes, in case this default behavior ever changes. A number of additional options are worth consideration as well, such as the -V option, which enables you to force the server to report a different version string than the one with which it was compiled. Many scripts run by script kiddies can be flagged off if you report a version with no known vulnerabilities, or confused into beating their heads against a brick wall if you report a different version with well-known vulnerabilities that don't correspond to problems with the server you're actually running.

Table 12.1. Run Time Options for the Default `ftpd`

Option	Function
`-a <anondir>`	Defines `<anondir>` as the directory to which a `chroot(2)` is performed for anonymous logins. Default is the home directory for the FTP user . This can also be specified with the `ftpd.conf(5) chroot` directive.
`-c <confdir>`	Changes the root directory of the configuration files from `/etc` to `<confdir>` . This changes the directory for the following files: `/etc/ ftpchroot` , `/etc/ftpusers` , `/etc/ftpwelcome` , `/etc/motd` , and the file specified by the `ftpd.conf(5) limit` directive.
`-C <user>`	Checks whether the user would be granted access under the restrictions given in `ftpusers(5)` and exits without attempting a connection. `ftpd` exits with an exit code of 0 if access would be granted, or 1 otherwise . This can be useful for testing configurations
`-d`	A facility of `LOG_FTP` is used to write debugging information to the `syslog` .
`-e <emailaddr>`	Uses `<emailaddr>` for the `%E` escape sequence
`-h <hostname>`	Explicitly sets the hostname to advertise as `<hostname>` . Default is the hostname associated with the IP address on which `ftpd` is listening. This capability (with or without `-h` ), in conjunction with `-c <confdir>` , is useful when configuring virtual FTP servers to listen on separate addresses as separate names .
`-H`	Equivalent to `“h <hostname>` .
`-l`	Logs each successful and failed FTP session by using `syslog` with a facility of `LOG_FTP` . If this option is specified more than once, the retrieve ( `get` ), store ( `put` ), append, delete, make directory, remove directory, and rename operations and their filename arguments are also logged.
`-P <dataport>`	Uses `<dataport>` as the data port, overriding the default of using the port one less than the port on which `ftpd` is listening.
`-q`	Enables the use of PID files for keeping track of the number of logged-in users per class. This is the default.
`-q`	Disables the use of PID files for keeping track of the number of logged-in users per class. This might reduce the load on heavily loaded FTP servers.
`-r`	Permanently drops root privileges after the user is logged in. The use of this option could result in the server using a port other than the listening port for `PORT` -style commands, which is contrary to the RFC 959 specification. In practice, though, very few clients rely on this behavior.
`-s`	Requires a secure authentication mechanism such as Kerberos or S/Key be used.
`-u`	Logs each concurrent FTP session to `/var/run/utmp` , making them visible to commands such as `who` (1).
`-u`	Doesn't log each concurrent FTP session to `/var/run/utmp` . This is the default.
`-V <version>`	Uses `version` as the version to advertise in the login banner and in the output of `STAT` and `SYST` , instead of the default version information. If version is `-` or empty, doesn't display any version information.
`-w`	Logs each FTP session to `/var/log/wtmp` , making them visible to commands such as `last` (1). This is the default.
`-w`	Doesn't log each FTP session to `/var/log/wtmp` .
`-X`	Logs wu-ftpd style `xferlog` entries to the `syslog` , prefixed with `xferlog:` , by using a facility of `LOG_FTP` . These `syslog` entries can be converted to a wu-ftpd style `xferlog` file suitable for input into a third-party log analysis tool with a command similar to the following: grep 'xferlog: ' /var/log/xferlog \ sed -e 's/^.*xferlog: //' > wuxferlog

Restricting Access

The lukemftpd FTP server uses three main configuration files for restricting access: /etc/ftpusers , /etc/ftpchroot , and /etc/ftpd.conf . By using these files you can place restrictions on who can use FTP to access your machine ”blocking certain users and allowing others. You can also configure limitations to the type and frequency of access granted by limiting the number of connections and setting timeouts and other server- related limits on FTP server availability and capability.

NOTE

If you want to take advantage of these features, but you're running the ftpd that comes with Mac OS X 10.2, you should update your version of the default ftpd . The distributed version contained a number of bugs that prevented access control from working properly. You can check the version by running strings /usr/libexec/ftpd grep "lukemftp" . Broken versions report version 1.1 . Version 1.2 beta 2 is known to work. Replacing lukemftpd with the most recent version is covered briefly in the next section.

An /etc/ftpusers file comes by default. This file contains the list of users who aren't allowed FTP access to the machine. Here's the default file:

 %  more /etc/ftpusers  # list of users disallowed any ftp access. # read by ftpd(8). Administrator administrator root uucp daemon unknown www

If you have additional users who shouldn't be granted FTP access, include them in this file. Also include any system logins that might not be listed by default in this file. Because the syntax for this file can be more complex, its documentation is included in Table 12.2.

The FTP server also allows for chroot ed FTP access, which is a compromise between full access and anonymous-only access. With this compromise access, a user is granted FTP access to only his home directory. List any users who should have this type of access in the /etc/ftpchroot file, which does not exist by default.

The last major configuration file for the default ftpd is /etc/ftpd.conf . In this file, you can define classes and various types of restrictions for a given class. This FTP server is supposed to understand three classes of user: REAL , CHROOT , and GUEST . A REAL user is a user who has full access to your machine. A CHROOT user is one who is restricted to his home directory or a directory otherwise specified in /etc/ftpd.conf . A GUEST user is one who can connect to the machine for anonymous FTP only.

The basic form of a line in ftpd.conf is

  <directive> <class> <argument>

Directives that appear later override directives that appear earlier. This enables you to define defaults by using wildcards and to provide more specific overrides later in the file. In addition to the defaults you see listed in the preceding file, other available controls include ones for limiting the upload and download storage rates, maximum uploadable file size , and port ranges. This last control can be useful for setting up your FTP server to work while a firewall is also running on your machine. It enables you to synchronize your FTP server's port usage and firewall port range restrictions. Table 12.3 details all the available directives for the /etc/ftpd.conf file.

Table 12.2. Documentation for `/etc/ftpusers` and `/etc/ftpchroot`

ftpusers ftpchroot	ftpd access control files
`/etc/ftpusers`	The `/etc/ftpusers` file provides user access control for `ftpd(8)` by defining which users may login. If the `/etc/ftpusers` file does not exist, all users are denied access. A `\` is the escape character. It can be used to escape the meaning of the comment character or, if it's the last character on a line, to extend a configuration directive across multiple lines. A `#` is the comment character, and all characters from it to the end of line are ignored (unless it's escaped with the escape character). The syntax of each line is `<userglob>[:<groupglob>][@<host>] [<directive> [<class>]]` . These elements are or are handled as follows : `<userglob>` is matched against the username, by using `fnmatch (3)` glob matching (for example, `f` ). `<groupglob>` is matched against all the groups that the user is a member of, by using `fnmatch(3)` glob matching (for example, `src` ). `<host>` is either a CIDR address (refer to `inet_net_pton(3)` ) to match against the remote address (for example, 1.2.3.4/24), or an `fnmatch(3)` glob to match against the remote hostname (for example, `*.netbsd.org` ). `<directive>` allows access to the user if set to `allow` or `yes` . Denies access to the user if set to `deny` or `no` , or if the directive is not present. `<class>` defines the class to use in `ftpd.conf(5)` . If `<class>` isn't given, it defaults to one of the following: `chroot` if there's a match in `/etc/ftpchroot` for the user. `guest` if the username is `anonymous` or `ftp` . `real` if neither of the preceding conditions is true. No further comparisons are attempted after the first successful match. If no match is found, the user is granted access. This syntax is backward compatible with the old syntax. If a user requests a guest login, the `ftpd(8)` server checks to see that both `anonymous` and `ftp` have access. So if you deny all users by default, you must add both `anonymous allow` and `ftp allow` to `/etc/ftpusers` to allow guest logins.
`/etc/ftpchroot`	The file `/etc/ftpchroot` is used to determine which users will have their session's root directory changed (using `chroot(2)` ), either to the directory specified in the `ftpd.conf(5) chroot` directive (if set), or to the home directory of the user. If the file doesn't exist, the root directory change is not performed. The syntax is similar to `/etc/ftpusers` , except that the class argument is ignored. If there's a positive match, the session's root directory is changed. No further comparisons are attempted after the first successful match. This syntax is backward compatible with the old syntax.

ftpusers ftpchroot

ftpd access control files

/etc/ftpusers

The /etc/ftpusers file provides user access control for ftpd(8) by defining which users may login.

If the /etc/ftpusers file does not exist, all users are denied access.

A \ is the escape character. It can be used to escape the meaning of the comment character or, if it's the last character on a line, to extend a configuration directive across multiple lines. A # is the comment character, and all characters from it to the end of line are ignored (unless it's escaped with the escape character).

The syntax of each line is <userglob>[:<groupglob>][@<host>] [<directive> [<class>]] .

These elements are or are handled as follows :

<userglob> is matched against the username, by using fnmatch (3) glob matching (for example, f* ).

<groupglob> is matched against all the groups that the user is a member of, by using fnmatch(3) glob matching (for example, *src ).

<host> is either a CIDR address (refer to inet_net_pton(3) ) to match against the remote address (for example, 1.2.3.4/24), or an fnmatch(3) glob to match against the remote hostname (for example, *.netbsd.org ).

<directive> allows access to the user if set to allow or yes . Denies access to the user if set to deny or no , or if the directive is not present.

<class> defines the class to use in ftpd.conf(5) .

If <class> isn't given, it defaults to one of the following:

chroot if there's a match in /etc/ftpchroot for the user.

guest if the username is anonymous or ftp .

real if neither of the preceding conditions is true.

No further comparisons are attempted after the first successful match. If no match is found, the user is granted access. This syntax is backward compatible with the old syntax.

If a user requests a guest login, the ftpd(8) server checks to see that both anonymous and ftp have access. So if you deny all users by default, you must add both anonymous allow and ftp allow to /etc/ftpusers to allow guest logins.

/etc/ftpchroot

The file /etc/ftpchroot is used to determine which users will have their session's root directory changed (using chroot(2) ), either to the directory specified in the ftpd.conf(5) chroot directive (if set), or to the home directory of the user. If the file doesn't exist, the root directory change is not performed.

The syntax is similar to /etc/ftpusers , except that the class argument is ignored. If there's a positive match, the session's root directory is changed. No further comparisons are attempted after the first successful match. This syntax is backward compatible with the old syntax.

Table 12.3. Documentation for `/etc/ftpd.conf`

`ftpd.conf`	`ftpd(8)` configuration file The `ftpd.conf` file specifies various configuration options for `ftpd(8)` that apply after a user has authenticated a connection. `ftpd.conf` consists of a series of lines, each of which may contain a configuration directive, a comment, or a blank line. Directives that appear later in the file override settings by previous directives. This allows wildcard entries to define defaults, and then have class-specific overrides. A directive line has the format: <command> <class> [<arguments>] A `\` is the escape character; it can be used to escape the meaning of the comment character, or if it is the last character on a line, it extends a configuration directive across multiple lines. A `#` is the comment character, and all characters from it to the end of line are ignored (unless it is escaped with the escape character). Each authenticated user is a member of a class, which is determined by `ftpusers(5)` . `<class>` is used to determine which `ftpd.conf` entries apply to the user. The following special classes exist when parsing entries in: `all` Matches any class `none` Matches no class Each class has a type, which may be one of the following: `GUEST` Guests (as per the `anonymous` and `ftp` logins). A `chroot(2)` is performed after login. `CHROOT chroot(2)` ed users (as per `ftpchroot(5)` ). A `chroot(2)` is performed after login. `REAL` Normal users. The `ftpd(8) STAT` command returns the class settings for the current user, unless the `private` directive is set for the class.
`advertise <class> host`
`advertize <class> host`	Sets the address to advertise in the response to the `PASV` and `LPSV` commands to the address for host (which may be either a hostname or IP address). This may be useful in some firewall configurations, although many FTP clients may not work if the address being advertised is different than the address to which they've connected. If `<class>` is none or no argument is given, it is disabled.
`checkportcmd <class> [off]`	Checks the `PORT` command for validity. The `PORT` command fails if the IP address specified does not match the FTP command connection, or if the remote TCP port number is less than `IPPORT_RESERVED` . It is strongly encouraged that this option be used, especially for sites concerned with potential security problems with FTP bounce attacks. If `<class>` is none or off is given, this feature is disabled; otherwise, it is enabled.
`chroot <class> [<pathformat>]`	If `<pathformat>` is not given or `<class>` is none, uses the default behavior (see the later discussion). Otherwise, `<pathformat>` is parsed to create a directory to `chroot(2)` into at login. `<pathformat>` can contain the following escape strings:
	Escape	Description
	`%c`	Classname
	`%d`	Home directory of user
	`%u`	User name
	`%%`	A % character
	Default root directory is CHROOT The user's home directory. GUEST If -a `<anondir>` is given, uses `<anondir>` ; otherwise uses the home directory of the FTP user. REAL By default no `chroot(2)` is performed.
`classtype <class> <type>`	Sets the class type of `<class>` to `<type>` (see earlier discussion).
`conversion <class> <suffix> [<type> <disable> <command>]`	Defines an automatic inline file conversion. If a file to retrieve ends in `<suffix>` , and a real file (without `<suffix>` ) exists, then the output of `<command>` is returned rather than the contents of the file. `<suffix>` The suffix to initiate the conversion. `<type>` A list of valid filetypes for the conversion. Valid types are: `f` (file), and `d` (directory). `<disable>` The name of the file that will prevent conversion if it exists. A filename of `.` prevents this disabling action (that is, the conversion is always permitted). `<command>` The command to run for the conversion. The first word should be the command's full pathname as `execv(3)` is used to execute the command. All instances of the word `%s` in the command are replaced with the requested file (without suffix). Conversion directives specified later in the file override.
`denyquick <class> [off]`	Enforces `ftpusers(5)` rules after the `USER` command is received, rather than after the `PASS` command is received. Although enabling this feature may allow information leakage about available accounts (for example, if you allow some users of a `REAL` or `CHROOT` class but not others), it is useful in preventing a denied user (such as root) from entering a password across an insecure connection. This option is strongly recommended for servers that run an anonymous-only service. If `<class>` is none or off is given, the feature is enabled; otherwise, it is disabled.
`display <class> [<file>]`	If `<file>` is not given or `<class>` is none, disables this. Otherwise, each time the user enters a new directory, checks whether <file> exists, and if so, displays its contents to the user. Escape sequences are supported.
`homedir <class> [<pathformat>]`	If `<pathformat>` is not given or `<class>` is none, uses the default behavior (see later discussion). Otherwise, `<pathformat>` is parsed to create a directory to change into upon login, and to use as the home directory of the user for tilde expansion in pathnames and so on. `<pathformat>` is parsed as per the chroot directive. The default home directory is the home directory of the user for `REAL` users, and `/` for `GUEST` and `CHROOT` users.
`limit <class> <count> [<file>]`	Limits the maximum number of concurrent connections for `<class>` to `<count>` , with 0 meaning unlimited connections. If the limit is exceeded and `<file>` is given, displays its contents to the user. If `<class>` is none or `<count>` is not specified, this feature is disabled. If `<file>` is a relative path , it will be searched for in `/etc` (which can be overridden with `-c <confdir>` ).
`maxfilesize <class> <size>`	Sets the maximum size of an uploaded file to size. If `<class>` is none or no argument is given, this feature is disabled.
`maxtimeout <class> <time>`	Sets the maximum timeout period that a client may request, defaulting to two hours. This cannot be less than 30 seconds, or the value for timeout. If `<class>` is none or time is not specified, sets to default of 2 hours.
`modify <class> [off]`	If `<class>` is none or off is given, disables the following commands: `CHMOD` , `DELE` , `MKD` , `RMD` , `RNFR` , and `UMASK` . Otherwise, enables them.
`motd <class> [<file>]`	If `<file>` is not given or `<class>` is none, this feature is disabled. Otherwise, uses `<file>` as the message-of-the-day file to display after login. Escape sequences are supported. If `<file>` is a relative path, it will be searched for in `/etc` (which can be overridden with `-c <confdir>` ).
`notify <class> [<fileglob>]`	If `<fileglob>` is not given or `<class>` is none, this feature is disabled. Otherwise, each time the user enters a new directory, notifies the user of any files matching `<fileglob>` .
`passive <class> [off]`	If `<class>` is none or off is given, prevents passive ( `PASV` , `LPSV` , and `EPSV` ) connections. Otherwise, enables them.
`portrange <class> <min> <max>`	Sets the range of port numbers that are used for the passive data port. `<max>` must be greater than `<min>` , and both numbers must be between `IPPORT_RESERVED` (1024) and 65535. If `<class>` is none or no arguments are given, this feature is disabled.
`private class [off]`	If `<class>` is none or off is given, does not display class information in the output of the `STAT` command. Otherwise, displays the information.
`rateget <class> <rate>`	Sets the maximum get ( `RETR` ) transfer rate throttle for `<class>` to rate bytes per second. If rate is 0, the throttle is disabled. If `<class>` is none or no arguments are given, disables this. An optional suffix may be provided, which changes the interpretation of `<rate>` as follows: `b` Causes no modification. (Default; optional) `k` `Kilo` ; multiplies the argument by 1024 `m` `Mega` ; multiplies the argument by 1048576 `g` `Giga` ; multiplies the argument by 1073741824 `t` `Tera` ; multiplies the argument by 1099511627776
`rateput <class> <rate>`	Sets the maximum put ( `STOR` ) transfer rate throttle for `<class>` to `<rate>` bytes per second. If `<class>` is none or no arguments are given, this feature is disabled.
`sanenames <class> [off]`	If `<class>` is none or off is given, allows uploaded file names to contain any characters valid for a filename. Otherwise, permits only file names which don't start with a `.` and are composed of only characters from the set [ `-+,._A-Za-z0-9` ].
`template <class> [< refclass >]`	Defines `<refclass>` as the template for `<class>` ; any reference to `<refclass>` in following directives will also apply to members of `<class>` . It is useful to define a template class so that other classes that are to share common attributes can be easily defined without unnecessary duplication. There can be only one template defined at a time. If `<refclass>` is not given, disables the template for `<class>` .
`timeout <class> <time>`	Sets the inactivity timeout period. This cannot be less than 30 seconds, or greater than the value for maxtimeout. If `<class>` is none or time is not specified, sets to the default of 15 minutes.
`umask <class> <umaskval>`	Sets the umask to `<umaskval>` . If `<class>` is none or `<umaskval>` is not specified, sets to the default of 027.
`upload <class> [off]`	If `<class>` is none or off is given, disables the following commands: `APPE` , `STOR` , and `STOU` , as well as the modify commands: `CHMOD` , `DELE` , `MKD` , `RMD` , `RNFR` , and `UMASK` . Otherwise, enables them. The following defaults are used: [View full width] checkportcmd all classtype chroot CHROOT classtype guest GUEST classtype real REAL display none limit all -1 # unlimited connections maxtimeout all 7200 # 2 hours modify all motd all motd notify none passive all timeout all 900 # 15 minutes umask all 027 upload all modify guest off umask guest 0707

Updating the Default ( `lukemftpd` ) `ftpd`

As mentioned earlier, if you want to take advantage of the default ftpd 's controls, and you're running the initial release of Mac OS X 10.2, you should update the ftpd . The controls for the ftpd that ships with this release don't work properly. Fortunately, the update is not difficult to perform. Even if you are not planning to take advantage of the default ftpd 's controls, but are planning to turn on ftpd , it is always a good idea to run the latest version; later versions usually contain security as well as functionality updates.

The default ftpd at this time is lukemftpd-1.1 . Recently lukemftpd has been renamed tnftpd . Download the latest version, currently tnftpd-2.0-beta3 , from here:

ftp://ftp.netbsd.org/pub/NetBSD/tnftp/

ftpd follows the basic format for compiling and even compiles easily under Mac OS X. Run ./configure and then make . As of version 2.0 beta3, make install doesn't seem to work, but you can copy the ftpd binary yourself. Make sure that you keep a backup of the default /usr/libexec/ftpd , just in case you need it. Make sure you keep a copy of the updated ftpd as well, in case you should ever find that Software Update has replaced your updated version with an older version again. At the top of the source directory, perform cp src/tnftpd /usr/libexec/ftpd . With this version of the FTP server, you can take advantage of the access controls, most notably the /etc/ftpchroot file, and anonymous FTP, if you already had anonymous FTP enabled from a previous version of Mac OS X.

Top

Configuring the Default lukemftpd FTP Server