From Wzdftpd

Contents 1 Config file directives 1.1 General configuration 1.1.1 IPs and ident 1.1.2 Symbolic links (symlinks) 1.1.3 Virtual File system (VFS) 1.1.4 Users and Groups 1.1.5 Passwords 1.1.6 Files and messages 1.1.7 Logging Channels 1.2 Directives reference

Config file directives

General configuration

• Lines beginning with a # are considered as comments

• Variables are organized in sections. The most important one is "GLOBAL", where all server parameters are stored. The name of the variable is also called a key, and the section a group.

• Section names are written with the name enclosed in brackets, for ex "[GLOBAL]"

• All variables are written using the standard form "key = value". Values can't be written on several lines. Multiples values must be separated by commas, for ex:

key = value1,value2

The main groups are "GLOBAL" (the server config), "perms", "modules", "cron", "sections", "events", "vfs" and "messages".

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 'allow'

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.

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-existent 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.

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-existent 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 absolutely 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 previously, 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.

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 example

site change foo ratio 0

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

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 example should demonstrate how setting group values is important, as you can use group values when you create users.

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 example: {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 example,

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 available methods and implementation.

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 example:

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

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.

Directives reference

backend (default: plaintext) 

The backend to use for authentication and user/group management. You can specify a test on the backend version if needed. See the glossary for explanation on what a backend is.

backend = /path/to/libwzdplaintext.so

backend = /path/to/libwzdplaintext.so > 122In these two examples, backend will be called 'plaintext'
You need at least one backend.

backup config (default: false) 

Make a backup of the configuration before saving changes. The backup will have the same name, with ".old" appended.
You must ensure that the user running the ftp server has the permission the create a file in the server's configuration directory.

backup config = true

bnc_list (default: empty) (ADVANCED, > 0.8.0) 

List of hosts allowed to act as FTP bouncers (comma-separated)

bnc_list = 127.0.0.1, 127.0.0.2

check_ip_before_login (default: 0) 

Specify 1 here to check the ip address of a client at the connection level, before any message is sent. The address is searched in all groups and clients, and if not found, the connection is closed without any reply (the banner

220 wzdftpd server ready.

is not sent, for example).

check_ip_before_login = 1

data_buffer_length (default: 16384) (ADVANCED, > 0.3.3) 

Change the size of the internal buffer used for data transfers.

data_buffer_length = 65536

Use this option carefully! This can have a big impact on transfer rates.

deny_access_files_uploaded (default: 0) 

Specify 1 here to deny access to files during their upload.

deny_access_files_uploaded = 1

dir_message 

When changing current directory, the server will look for this file, and if present will append it to the end of the ftp reply.

dir_message = .message

disable core (default: no) 

Disable the creation of a core file if the server crash.

disable core = yes

disable_ident (default: no) 

Completely disable all ident lookups when a client connects.

disable_ident = yes

disable_tls (default: no) 

Completely disable TLS/SSL support (even if compiled in).

disable_tls = yes

dynamic_ip (default: 0) 

If you specify 1 or an ip, the server will try to detect ip changes (e.g DSL disconnections).

dynamic_ip = 1

dynamic_ip = xxx.myftp.org0 means the option is deactivated, 1 the server will ask the system to find its ip, otherwise the server will perform DNS lookups

hide_dotted_files (default: 0) 

Specify 1 here to hide files beginning with a dot ('.')

hide_dotted_files = 1

log_channel_... (default: use logfile or syslog) 

Change log file associated to a specific channel. The first 10 channels are reserved for standard log levels (from debug messages to critical errors), others can be used by backends or modules. To know the level associated to a module please consult the corresponding docs.

log_channel_21 = /var/log/wzdftpd/plaintext.log

To disable a channel, just leave empty the file name field:

log_channel_21 =

logdir (default: do not use log directory) 

Location of a directory where the server will put various log files.

logdir = /var/log/wzdftpd

logfile (default: do not use log file) 

Log file for server activity (see use_syslog)

logfile = /path/to/wzd.log

loglevel (default: normal) 

Controls the verbosity of the server in the log file.

loglevel = high

This means only messages important or critical error messages will be logged (and as this is higher than 'normal', many normal messages will be ignored). To the contrary, if you set loglevel to 'lowest', you will get ALL messages (even debug).
level can be one of (in order): lowest, flood, info, normal, high, critical
See also: Log Channels for more details.

max_dl_speed (default: 0) 

Maximum cumulated (for all users connected) download speed in bytes/sec.

max_dl_speed = 300000

max_threads (default: 32) 

The hard limit for child threads (clients connected simultaneously).

max_threads = 50

max_ul_speed (default: 0) 

Maximum cumulated (for all users connected) upload speed in bytes/sec.

max_ul_speed = 300000

pasv_high_range (default: 65536) 

The higher bound of ip range the server can take.

pasv_high_range = 3000

pasv_ip (default: *) 

Specify passive ip.

pasv_ip = 64.xxx.xxx.xxx

pasv_low_range (default: 1025) 

The lower bound of ip range the server can take.

pasv_low_range = 2500

pid_file (default: /var/run/wzdftpd.pid) 

File where pid of server will be stored. This is used by init.d scripts to send signals to server.

pid_file = /path/to/wzdftpd.pid

port (default: 21) Changed in 0.6.0 ! 

The port to listen.

port = 1321

IMPORTANT: under non-Windows, you need privileges to bind to a system port ( < 1024 )
Since 0.6.0, this option controls the port AND the ip to bind to. If you specify

port = 1321

, the server will bind to all interfaces on port 1321, and in IPv6 if available.
To bind to a specific ip address, just use the ip:port syntax:

ip = 127.0.0.1:1321

The server will understand IPv6 addresses:

ip = ::1:1321

This option is multi-valued, so if you want to bind to several ip/ports, just use commas to separate the values:

ip = 1321, 192.168.0.100:1234

The server will listen on all specified addresses and ports.

reject_unknown_users (default: 1) 

This options defines the behavior of the server if the user is not accepted. The default (1) will immediately reject user and close connection, while setting 0 will cause the server to continue the login process (sending a password request) and reject user after.

reject_unknown_users = 0

This option can be used for more security, to prevent a client from detecting user names.

server_gid (default: none) 

Change the group ID of the server after binding port. This is useful only if server is running as root

server_gid = users

server_uid (default: none) 

Non-Windows server will drop privileges and change its uid to server_uid after binding port. This is useful only if server is runned by root.

server_uid = toto

IMPORTANT: under Non-Windows, you need privileges to bind to a system port ( < 1024 )

server tick (default: 10) (ADVANCED, > 0.6.1) 

The maximum duration time, in seconds, for the main server loop (waiting for connections).

server tick = 10

site_ 

Custom site commands. : Since 0.6.0, custom scripts are defined in the "custom_commands" section. (Ultimately, this will allow to define general custom commands, not only site commands. Syntax is commandname = action

[custom_commands]

site_myls = /path/to/myls.sh

site_rules = !/path/to/rules.txtIf the first character of the command is !, then the command with return to the client the content of the specified file (replacing cookies).

use_syslog (default: 1, except for cygwin) 

Use syslog to log server messages (see logfile)

use_syslog = 1

tls_certificate [TLS only] 

The name of the TLS certificate to use.

tls_certificate = /path/to/wzd.pem

tls_certificate_key [TLS only] ( wzdftpd >= 0.5 ) 

The name of the TLS certificate key file to use.

tls_certificate_key = /path/to/wzd_key.pem

If not specified, the server will try to use the certificate for the key file.

tls_cipher_list (default: ALL) [TLS only] 

The cipher list server will negotiate during TLS handshake

tls_cipher_list = ALL

You should not use this option, or let "ALL", unless you know what you are doing.
see openssl ciphers, man openssl(1)

tls_mode (default: explicit) [TLS only] 

Use implicit, explicit or explicit_strict mode (see tls modes for details)

tls_mode = explicit

umask (default: 775) 

This is the permissions that are set when a new directory is created. Permissions are written in octal with the default format (permissions for owner, group, others).

umask = 755

The default permissions (775) allow every user from the same group to write files in the directory.
Remember that DELETE permission is managed in a different way - unlike unix, it's not because you have the write permission that you can delete files in it. In fact, unless you specify an explicit permission on config file, only the owner of a file (and siteop) can delete a file.

xferlog (default: do not log) 

Log transferred files in common xferlog format (suitable for analysis with classical tools).

xferlog = /path/to/xferlog