Chapter 2. Config file directives

Table of Contents
2.1. General configuration
2.1.1. IPs and ident
2.1.2. Symbolic links (symlinks)
2.1.3. Virtual File system (VFS)
2.1.4. Users and Groups
2.1.5. Passwords
2.1.6. Files and messages
2.1.7. Logging Channels
2.2. Directives reference

2.1. General configuration

IMPORTANT: starting from 0.6.0, the config file format has changed. wzdftpd now uses a .ini like config:

2.1.1. IPs and ident

wzdftpd gives the possibility to check user identity on connection.

To permanently disable ident lookups for all users, set the disable_ident variable to 1 or 'yes'

Wildcards are accepted

You can use dynamic ip (e.g xxx.no-ip.com), server will resolve it at runtime.

When you specify an ip, it means all ident from this ip address are allowed. If you want to restrict connection for a specific ident: just add 'ident@' in front of the ip.

ip = ident@host.domain.com

IMPORTANT: This option is DIFFERENT from other ftpd's . Instead of specifying '*@ip', just write the ip (wzdftpd understands the fact you don't give any ident as an implicit authorization for all idents).

NOTE for 0.3 users: signs in front of ip have disappeared and are no more needed (+ and -). Just remove them.

2.1.2. Symbolic links (symlinks)

Symbolic links are often used on linux and unix systems, so users of these systems should have no difficulty to use this. A symbolic link (symlink, in short) is a link between a non-existant directory (so-called virtual directory) and an existing directory (so-called physical directory). This allows, for example, to create a directory whose contents are on another physical drive. This is similar to windows shortcuts.

Symlinks are created online, using the site link commands.

site link create /music link

This will create a symbolic link 'link' in the current directory, which points to '/music' (at the homedir of the user).

On windows, symlinks can't be seen on the filesystem (so do not search directories in explorer), they are fully handled by server.

You can set permissions on links just as for any other directory, with the same commands (chmod, etc).

Note on performance (windows only): please note that symlinks are emulated, and you will therefore suffer a small penalty on speed, compared to real directories. However, this generally does not slow down the server enough to be be important, and symlinks are lighter than VFS.

2.1.3. Virtual File system (VFS)

wzdftpd offers the possibility to use virtual directories, also known as VFS. A VFS is a kind of link between a non-existant directory (so-called virtual directory) and an existing directory (so-called physical directory). This allows, for example, to create a directory whose contents are on another physical drive.

Unlike symlinks (which are create online), VFS are stored in the config file.

vfs = |/home/pollux/vfs|/etc|

This will create a virtual directory 'vfs' in '/home/pollux', which will be abolutely equivalent to '/etc'.

Change in 0.6.0: vfs are defined in the "vfs" section, so the syntax is slightly changed:

customname = |vfspath|realpath|
customname = |vfspath|realpath| permissions
For ex:


[vfs]
vfs1 = |/home/pollux/vfs|/etc|

You can use restrictions on VFS, to allow only specified users to see and use them. Note this is only the ability to see and use VFS, and does not affect permissions on directories or files contained in VFS.

vfs = |/home/pollux/vfs|/etc| +O =admin

This will define the same VFS as precedently, restricted only to siteops (+O flag) and members of the group 'admin' (=admin).

It would be fastidious to define VFS for all users and groups, for example. To help you in this task, wzdftpd allows you to use a small subset of cookies, to have a set of wildcards for users, groups, etc.

vfs = |%userhome/etc|/etc| +O =admin

This will create a virtual dir called 'etc' in the homedir of every siteop and member of admin group, equivalent to /etc.

For the moment, supported cookies are username, usergroup, and userhome.

Note on performance: please note that VFS are emulated, and you will therefore suffer a small penalty on speed, compared to real directories. This penalty will be increased if you use cookies.

If you don't know what to choose between symlinks and VFS, read this FAQ entry.

2.1.4. Users and Groups

wzdftpd, unlike many other ftpd daemons, is very oriented on groups. The idea is to create groups with specific properties, and make users belong to several groups. It simplifies configuration, because instead of configuring each user, you just have to configure groups. However, please remember that the first group of a user is special (it is his main group).

For example, setting the defaultpath in a group is specially important, because it will be used as a default value each time you create a user. The default ratio will also be taken from the group's ratio.

Also, do not forget that when a user is created, it has no default ip allowed. If you authorize an ip for the group, it will be allowed for all users.

For users without specific idle time limit, the value of the group will be checked. So, user value is needed only if different from group.

Here is the standard procedure to add a user: Use

site adduser foo pass users
to create user 'foo' with password 'pass', and belonging to the main group 'users'. Note that at this point, foo will not be able to log in, mainly because it has no allowed ip (except under some conditions that we'll see later).

Now add an authorized ip with

site addip foo *
or
site addip foo foobar@127.0.0.1
if you want an ident check.

The default ratio of foo is inherited from the group 'users', in this case we will suppose 1:3. If you want to change it you can use for exemple

site change foo ratio 0

The default homedir for foo is also inherited from group 'users', you can change it with for exemple:

site change foo homedir /home/ftp

Please note that adding an authorized ip is also optional, as every ip authorized for the group is authorized for each group member.

This short exemple should demonstrate how setting group values is important, as you can use group values when you create users.

2.1.5. Passwords

Since version 0.6.0, authentication is managed by a dedicated component, which supports several authentication methods, including: passwords, certificates, and third-party modules (like PAM).

Each method is associated to a prefix, fox exemple: {SHA} for SHA-1 encryption, {cert} for certificates, etc. The method is specified when changing a password by writing it just before the password. For exemple,

site chpass username {SHA}newpass
will change password for user username, set it to newpass, and store it encrypted in SHA-1 format.

If the selected method does not use passwords (like certificates), just specify the prefix:

site chpass username {cert}

If no authentication method is specified, then the default is to store the password encrypted in crypt format.

See authentication chapter for details on availables methods and implementation.

2.1.6. Files and messages

You can customize server replies (under certain conditions, you must always be RFC-compliant if you want your server to work). This requires some little knowledge of FTP, but there are some well-known messages you can easily modify:

Message 220 is known as 'FTP Banner', it is what the client sees when he connects. The default is:

220 = wzd server ready.

Message 230 is known as 'Welcome Message', it is what the server sends to the client when the connection request has been accepted, and the login/password validated. It is generally used to show statistics about server, etc. The default message is:

230 = User logged in, proceed.

Message 221 is sent when client disconnects. The default message is

221 = Cya !

Of course, using this would limit messages to only one line per message .. so you can put a message in a file and use the file name as argument for the precedent commands, just prefix the file name with a + (the server will not guess this is a filename otherwise):

230 = +/path/to/my/welcome.msg

Remember you can use cookies in your messages, but keep in mind that cookies are NOT always available (sometimes it just doesn't make sense). For exemple:

230 = hello, %username.
will actually work, whereas
220 = wzd server for %username
will NOT, because at the moment the message 220 is sent the server does not know the user name (he isn't authenticated yet).

If the server can't translate a cookie into its value, the cookie name will be written as is: '%username' will return 'username'

NOTE: messages are defined in the "messages" section of the config

2.1.7. Logging Channels

Since version 0.5.4, wzdftpd uses the idea of channels to redirect logs. Each line logged is associated with a unique number (the channel), and each channel is associated to a configuration: do not log, log to a file and/or to syslog.

There are 10 predefined channels, reserved for standard server logs. They are organized in order of importance: the lowest number corresponds to debug, the highest to critical error messages. The loglevel config directive is used to select only interesting levels: if loglevel is set to normal, only messages with at least this level will be logged.

Other log channels are used differently: their value is not used to control verbosity, but only as a selector: you can choose to redirect messages to the standard log, or to redirect messages concerning a specific level to a different log file, etc. (this can also be done for standard channels). The log_channelconfig directive is used to change destination of channels.