Muddleftpd reference text. Copyright Beau Kuiper 2000. 1.0 Config file format overview 1.0.1 Main sections 1.0.2 Virtual server sections 1.0.3 Group sections. 1.1 Directive reference 1.1.1 Quick reference This is a quick list of all muddleftpd directives, and where they are valid. access (group) altlongreplies (main) authmethod (group) authuser (group) badauthwait (virtual-server, main) busydump (group) busydumpdata (group) byteratios (group) cddump (group) cddumpdata (group) chmoding (group) chroot (group) cmdoff (group) devaccess (group) droproot (group) email (virtual-server, main) fakegroup (group) fakemode (group) fakename (group) fileratios (group) fnaccess (group) ftpport (virtual-server, main) fxpallow (group) gid (group) greeting (virtual-server, main) group (virtual-server, main) homedir (group) hostname (virtual-server, main) include initalbytes (group) initalfiles (group) ipacl (virtual-server, main, group) logfile (virtual-server, main) logindump (virtual-server, main) logindumpdata (virtual-server, main) logintries (virtual-server, main) logstrength (virtual-server, main) maxconnectperip (virtual-server, main) maxspeed (group) maxusers (virtual-server, main, group) nameacl (group) nice (group) pfnaccess (group) quitdump (group) quitdumpdata (group) ratiofile (group) ratios (group) rdnstimeout (main) realdir (group) rootdir (group) runasuser (main) sitecmdoff (group) smartbind (main) supgid (group) timeout (virtual-server, main, group) uid (group) umask (virtual-server, main, group) userjail (group) vserver (main) welcome (group) welcomedumpdata (group) zerobind (main) 1.1.2 Detailed reference 1.1.2.1 "access" directive Used in: group sections Syntax: access [DIR]:[MODE] Examples: access %h/:ALL # give all access to home directory access /secure/:NONE # deny all access to /secure directory access /:RCL # only allow reading, listing and # chdir to users Cookie support: Yes, see 1.2.2 Default: access /:NONE access is used to change the permissions on files or directories muddleftpd gives to users logged into a particular group. If [DIR] ends with /, then muddleftpd assumes it is refering to a directory and permissions only apply to files in the directory, not [DIR] itself. Otherwise, muddleftpd assumes it is a file, and the permissions will only apply to that filename. [MODE] is documented in 1.2.1. WARNING: when a symbolic link is encountered, muddleftpd will apply the access directives to the symbolic link only, not to the destination of the symbolic link. Users who can create symbolic links in the same areas they access with the ftp server will be able to easily circumvent the access directives. Therefore you MUST not depend on access being safe in groups where the user can create symbolic links in the same area as they can access via the ftp server. 1.1.2.2 "altlongreplies" directive Used in: main section Syntax: altlongreplies [VALUE] Examples: altlongreplies 0 # use rfc format for long replies altlongreplies 1 # use more compatible format for # long replies Cookie support: No Default: altlongreplies 0 altlongreplies makes muddleftpd use a different format for long FTP replies. When set to 1, it uses the following format for long replies: 220-Start long reply 220-Contiune 220 End long reply When set to 0, it uses this format: 220-Start long reply Continue 220 End long reply. When set to 1, muddleftpd may be more compatible with older clients and proxies. 1.1.2.3 "authmethod" directive Used in: group sections Syntax: authmethod [modulename] Examples: authmethod pam # use pam to authenticate users authmethod unix # use unix passwd to authenticate # users. authmethod /etc/muddleftpd/libauthmysql.so # use external authentication module. Cookie support: Yes, see 1.2.2 Default: (none), you must specify this. authmethod sets how muddleftpd chooses a user's group and how that user is authenticated. You can specify one of the internal authentication modules (unix,pam,internal,anonymous,deny) or an external module. If you use an external authentication module, its full path MUST be specified. Section 2.0 outlines 1.1.2.4 "authuser" directive Used in: group sections Syntax: authuser [username] Examples: authuser %U # no rewriting. authuser %U-servb # add the suffix -servb to the # username authuser %(5,100)U # remove first 5 characters of # username Cookie support: Yes, see 1.2.2 Default: authuser %U Authuser allows the server to do some very basic rewriting of the username before passing it to the authentication module (specifed in authmodule). This re-written username is ONLY used when communicating with the authentication module, and the original username is used everywhere else. 1.1.2.5 "badauthwait" directive Used in: virtual server sections or the main section. If virtual servers are defined, any occurence in the main section is taken as the default for virtual servers. Syntax: badauthwait [milliseconds] Examples: badauthwait 2000 # wait 2 seconds badauthwait 500 # wait 1/2 second Cookie support: No Default: badauthwait 3000 When a login fails (PASS command) for any reason, muddleftpd will wait a defined time before accepting a new command. Use this option to specify an appropriate time for muddleftpd to wait. 1.1.2.6 "busydump" directive Used in: group sections Syntax: busydump [filename] Examples: busydump /etc/muddleftpd/TOOBUSY # print this when too many users # are on Cookie support: Yes, see 1.2.2 Default: (none) When the server cannot log a user into a particular group due to maxusers limits, it will print this message before disconnecting the user from the server. This is not used when the server's or the virtual server's maxusers limit is reaches. When this occurs, the user is simply disconnected without any messages. Section 1.2.4 documents cookies you can use in files specified with this directive. The file must given with a full path. 1.1.2.7 "busydumpdata" directive Used in: group sections Syntax: busydumpdata [dump-string] Examples: busydumpdata Cannot log you in/nMaximum %M users exceeded./n # print this when too many users # are on Cookie support: Yes, see 1.2.4 Default: (none) This command is exactly like busydump (1.1.2.7), except the actual data is stored in the config file instead of an external file. The format for [dump-string] is described in section 1.2.3. This overrides any busydump directives in the same section. 1.1.2.8 "byteratios" directive Used in: group sections, only valid if ratios is set to 1 Syntax: byteratios [down:up] Examples: byteratios 10:3 # for every 3 bytes the user uploads # give 10 bytes of download credit. byteratios 1:5 # for every 5 bytes the user uploads # give 1 byte of credit. Cookie support: No Default: (none) This directive sets the ratios that will be placed on byte usage for users not found in the ratio file. (users in the ratio file have already got a ratio stored) If no ratio file is given, this will always be used. 1.1.2.9 "cddump" directive Used in: group sections Syntax: cddump [filename] Examples: cddump README # print the README file in the # directory the user is entering cddump /etc/cdinfo # print /etc/cdinfo out. Cookie support: Yes, see 1.2.2 Default: (none) When a user changes directory, this file will be printed. If it is relative filename (no / at the beginning), then the file will relative to the new directory the user is entering. A relativly specified file will also have to be normally accessable to the user via permissions and access directives. If the file is specified absolute (with a / at the beginning) then muddleftpd will not check it against access directives. Absolute files are not relative to rootdir. 1.1.2.10 "cddumpdata" directive Used in: group sections Syntax: cddumpdata [dump-string] Examples: cddumpdata You changed dir/nIt is now %C/n # print this when muddleftpd changes # dir Cookie support: Yes, see 1.2.4 Default: (none) This command is exactly like cddump (1.1.2.9), except the actual data is stored in the config file instead of an external file. The format for [dump-string] is described in section 1.2.3. This overrides any cddump directives in the same section. 1.1.2.11 "chmoding" directive Used in: group sections Syntax: chmoding [0 or 1] Examples: chmoding 1 # allow site chmod chmoding 0 # disallow site chmod Cookie support: Yes, see 1.2.2 Default: chmoding 0 This command controls whether users can change the permissions on files using "site chmod". By default, it is 0 and users cannot change file permissions on ANY files. Setting it to 1 will enable this ability. 1.1.2.12 "chroot" directive Used in: group sections Syntax: chroot [VALUE] Examples: chroot 1 # chroot after successful login chroot 0 # don't chroot after successful # login Cookie support: Yes, see 1.2.2 Default: chroot 0 This controls whether muddleftpd will change the system root directory to the users rootdir after login is complete. This means symbolic links that point outside of the users rootdir will NOT work. It has the following side effects: 1) userjail is set to 1, thus the user cannot login again. 2) welcome, cddump and quitdump, will complain if you attempt to use files outside of rootdir 3) log messages for file operations will now have filenames absolute to the user's rootdir. (may be fixed later) 4) log rotation will not be done for any muddleftpd process that has performed chroot. 1.1.2.13 "cmdoff" directive Used in: group sections Syntax: cmdoff [CMD] Examples: cmdoff SITE # disable all site commands. cmdoff PASV # disable passive transfers. cmdoff DELE # disable file deletion. Cookie support: Yes, see 1.2.2 Default: (none) This directive disables FTP commands. This can disable things like file rename, deleting, storing files, ect. When commands are disabled, they appear unimplemented to the user (ie, they become no different to commands that don't exist). See section 3.1 for commands that can be disabled with this command. 1.1.2.14 "devaccess" directive Used in: group sections Syntax: devaccess [VALUE] Examples: devaccess 1 # enable access to device files. devaccess 0 # disable access to device files. Cookie support: Yes, see 1.2.2 Default: devaccess 0 This directive sets whether users in a group can access device files. The default is to disallow this, although it does incur a very small performace penalty. (file must be checked to make sure it isn't a device). Attempting to access a device will result in a permission error. 1.1.2.15 "droproot" directive Used in: group sections Syntax: droproot [VALUE] Examples: droproot 1 # drop all root privliges after # login droproot 0 # don't drop root privliges. Cookie support: Yes, see 1.2.2 Default: droproot 0 This directive sets whether the server will drop all root privlidges after login. When enabled, security for the paranoid is enhanced (muddleftpd doesn't have root exploits), but: 1) muddleftpd cannot bind the server data port to 20. This means that ftp clients may not work through firewalls. However, this limitation will automaticly be removed if you have linux and the capibilities library installed. 2) userjail is set to 1. (user cannot relogin as another user) 3) logfiles cannot be rotated by any muddleftpd process that has a user logged into a group where droproot is set. 1.1.2.16 "email" directive Used in: virtual server sections or the main section. If virtual servers are defined, any occurence in the main section is taken as the default for virtual servers. Syntax: email [STRING] Examples: email ftpadmin@ftp.host.com # set email to this email user@hostname # another silly example Cookie support: No Default: email ftp@localhost This sets the email address returned when the HELP ftp command is used, and when the %e cookie is used in dumped files or strings. This can be anything you want really. 1.1.2.17 "fakegroup" directive Used in: group sections Syntax: fakegroup [STRING] Examples: fakegroup mudgroup # set group to mudgroup fakegroup anonymous # set group to anonymous Cookie support: Yes, see section 1.2.2 Default: (none) This is used to hide all group names in all listings, replacing them with the name you specify for the given group. This can hide the real group names in the group files from ftp users. 1.1.2.18 "fakemode" directive Used in: group sections Syntax: fakemode [OCTAL-VALUE] Examples: fakemode 777 # set mode to rwxrwxrwx fakemode 700 # set mode to rwx------ Cookie support: Yes, see section 1.2.2 Default: (none) This specifies that listings should always return a certain mode for filenames. This hides the real permissions from the ftp user. 1.1.2.19 "fakename" directive Used in: group sections Syntax: fakename [STRING] Examples: fakename mud # set username to mud fakename mp3 # set username to mp3 fakename %U # set username to the login username Cookie support: Yes, see section 1.2.2 Default: (none) This specifies that listings should always return a certain user ownership for files. This hides the files original owner from ftp users. 1.1.2.20 "fileratios" directive Used in: group sections, only valid if ratios is set to 1 Syntax: fileratios [down:up] Examples: fileratios 2:1 # for every file the user uploads # allow 2 to be downloaded fileratios 1:5 # for every 5 bytes the user uploads # give 1 byte of credit. Cookie support: No Default: (none) This sets inital ratios on how many files a user must upload to how many credits they recieve for doing so. This will not override information in the ratio file. If no ratio file is specified, this is always used. 1.1.2.21 "fnaccess" directive Used in: group sections Syntax: fnaccess [PATTERN]:[MODE] Examples: fnaccess *.mp3:NONE # no access to files with mp3 # extension fnaccess *.o:NONE # no access to object files. fnaccess /home/%U/*:R # give read access to all files in # user home dir and subdirs Cookie support: Yes, see section 1.2.2. Default: (none) This specifies access setting using basic regular expressions. fnaccess setting have priority over regular access directives, so care must be exercised in the specifing fnaccess directives. Eg, access /:C access /home/mud/:LC fnaccess *.c:R will allow access to filenames /a.c or /home/a.c. Also, fnaccess directives are checked in the order they are specified in the config file, so fnaccess directives specified earilier have higher priority over fnaccess directives specified later. WARNING: when a symbolic link is encountered, muddleftpd will apply the fnaccess directives to the symbolic link only, not to the destination of the symbolic link. Users who can create symbolic links in the same areas they access with the ftp server will be able to easily circumvent the fnaccess directives. Therefore you MUST not depend on fnaccess being safe in groups where the user can create symbolic links in the same area as they can access via the ftp server. 1.1.2.22 "ftpport" directive Used in: either the main section or virtual server sections. If used in the main section when virtual servers are defined, then the declaration in the main section is ignored. Syntax: ftpport [PORTNUM] or ftpport [PORTNUM]:[IPADDR] Examples: ftpport 21 # bind to port 21, all interfaces ftpport 21:10.1.1.1 # bind to port 21, interface # on 10.1.1.1 only ftpport 4008 # bind to port 4008. Cookie support: No Default: (none), must be specified. This directive specifies what ports muddleftpd will listen for connections on. It may be specified more than once in the same section, where muddleftpd will listen for all specified ports. If you don't supply the ip of an interface to bind to, muddleftpd will listen on all ports. When setting up virtual servers, it is often done by using the same port, while using a different ip for the interface in each virtual server definition. 1.1.2.23 "fxpallow" directive Used in: group sections Syntax: fxpallow [VALUE] Examples: fxpallow 0 # disallow server-server transfers. fxpallow 1 # allow server-server transfers. Cookie support: Yes, see section 1.2.2. Default: fxpallow 0 This directive specifies whether users of a particular group can perform server to server transfers. It is highly recommended that you do not set this unless you really, really need to. Setting this to true allows users to send a file to an abitary port (above 1024) on any remote server. It also allows a third party to steal a passive connection from a user from any remote computer. 1.1.2.24 "gid" directive Used in: group sections Syntax: gid [VALUE or NAME] Examples: gid %g # set gid from users gid from authentication # module gid 10 # set users group to 10 gid ftpuser # set the users group to ftpuser. Cookie support: Yes, see section 1.2.2. Default: gid %g This specifies what gid a user connected to the server will use to access files. It can be specified using a group name or an integer group value. By default, the gid from the authentication module is used. If you set it to 0 (the root group), then muddleftpd will automaticly demote it to nobody's group. 1.1.2.25 "greeting" directive Used in: virtual server sections or the main section. If virtual servers are defined, any occurence in the main section is taken as the default for virtual servers. Syntax: greeting [STRING] Examples: greeting Welcome to %L # set greeting to display # server name Cookie support: Yes, see section 1.2.4 Default: greeting muddleftpd (1.3.4-devel) server ready. Enter Username. Sets the greeting line when a person connects to the server. This accepts all of the cookies the logindump file will accept. This is used to personalize your server and hide the server name, version from users. 1.1.2.26 "group" directive Used in: either the main section or virtual server sections. If used in the main section when virtual servers are defined, then the declarations in the main section are ignored. Syntax: group [SECTION] Examples: group badusers # set to check badusers section first group anonymous # set to check anonymous section next group users # set to check users section last or group badsites # check badsites section first group users # then users section next Cookie support: No Default: (none), must be specified. This directive sets the sections muddleftpd will check as groups when logging someone in to the server, or one of its virtual servers. The groups are checked in the same order as specified in the config file. Group sections are discussed in detail in section 1.0.3 1.1.2.27 "homedir" directive Used in: group sections Syntax: homedir [DIRECTORY] Examples: homedir / # set homedir to same as rootdir homedir %h # set homedir to homedir from # authentication module. Cookie support: Yes, see section 1.2.2. Default: homedir %h This directive describes the home directory a user logging in will have. It is ALWAYS relative to the rootdir. This is so users don't have homedir's outside of their root directory. By default, homedir is set by the authentication module. 1.1.2.28 "hostname" directive Used in: virtual server sections or the main section. If virtual servers are defined, any occurence in the main section is taken as the default for virtual servers. Syntax: hostname [STRING] Examples: hostname mud.serious.net # a hostname hostname hostname # another example Cookie support: No Default: (same as the hostname from /etc/HOSTNAME) This sets the hostname muddleftpd will report to users when they use the ftp server. It sets the %L cookie for files dumped to the user (see section 1.2.4). It also sets the %V cookie for group sections (see section 1.2.2) 1.1.2.29 "include" directive Used in: anywhere Syntax: include [SECTIONNAME] Examples: include asection # include section asection Cookie support: No Default: (none) This is a low level function that allows a section to be included into another section. No cookies are interpretted by include. An example: [section] a hostname v access /:ALL access /test/:NONE [section] b access /:NONE include a access /test/:ALL when section b is interpreted, will become access /:NONE hostname v access /:ALL access /test/:NONE access /test/:ALL Here, the included data is inserted in order, so you must be careful of the order the final result will be. In this example, the access to / is overriden by the data in the included section. 1.1.2.30 "initalbytes" directive Used in: group sections, only valid if ratios is set to 1, and byteratios is set (see 1.1.2.8) Syntax: initalbytes [64bit-INT] Examples: initalbytes 2000000 # give 2 meg of inital credits. initalbytes 0 # give 0 meg of credits initally. Cookie support: No Default: (none) This sets how many byte credits a user has initally when using ratios. If you have ratiofile defined, then this is only used for new users. Otherwise the setting will be read from the ratiofile. This is specified as a 64-bit integer (ie, can have virtually any size) 1.1.2.31 "initalfiles" directive Used in: group sections, only valid if ratios is set to 1, and fileratios is set (see 1.1.2.20) Syntax: initalfiles [COUNT] Examples: initalfiles 100 # give 100 inital file credits. initalfiles 0 # give 0 file credits initally. Cookie support: No Default: (none) This sets how many file credits a user has initally when using ratios. If you have ratiofile defined, then this is only used for new users. Otherwise the setting will be read from the ratiofile. 1.1.2.32 "ipacl" directive Used in: main, vserver and group sections Syntax: ipacl [A or D]/[IP]/[NETMASK] ipacl [A or D]/[IP-PATTERN] ipacl [A or D]/([HOST-PATTERN]) Examples: ipacl A/10.1.1.0/255.255.255.0 # allow 10.X.X.X ipacl A/127.* # allow localhost addresses ipacl A/(localhost) # allow hostname localhost ipacl A/(*.edu) # allow any .edu address ipacl D/(*.com.??) # disallow country .com Cookie support: No Default: ipacl D/* Ipacl is a generic way of declaring what IP address/hostnames have access to something. The first format above allows you to specify a range of IP's using an ip address and a netmask. The second format allows you to specify a range of IP's using a basic regular expressions. The third fromat allows you to sepecify a basic regular expression to match the user's hostname. You must be very careful when using regular expressions against hostnames. Users may spoof DNS and their hostname, allowing them to get accesss they otherwise shouldn't have. Ipacl's are checked in the order they are in the config file. The first ipacl to match the user's hostname or IP will decide the access of a particular user. The access a user will get is defined by the first character before ':', an 'A' will grant access, anything else will deny it. When used in the main section, ipacl controls who is given access to the server. If the user is not accepted by these controls, they are dumped from the server immediately. If virtual servers are defined, ipacl's in the virtual server section decide if the user is accepted into the server (after the main ones are checked). In group sections, ipacl controls if a user can login to that group after the user has entered a username/password. If the user is not accepted, muddleftpd will check the next group. 1.1.2.33 "logfile" directive Used in: virtual server sections or the main section. Syntax: logfile [FILENAME] Examples: logfile /var/log/ftpd.log # set logfile Cookie support: No Default: logfile /var/log/muddleftpd.log Sets the logfile for muddleftpd logs. This file must be an absolute filename. When defined in virtual server sections, muddleftpd will log information users using that virual server into that file instead of the main log file. The parameter to logfile must be an absolute filename. (ie start with /) 1.1.2.34 "logindump" directive Used in: virtual server sections or the main section. If virtual servers are defined, any occurence in the main section is taken as the default for virtual servers. Syntax: logindump [filename] Examples: logindump /etc/issue # print this before user logs in Cookie support: No Default: (none) When a new user connection to the server occurs, this is printed before the greeting (see section 1.1.2.25). All new users will see this file before they login using a username/password. 1.1.2.35 "logindumpdata" directive Used in: virtual server sections or the main section. If virtual servers are defined, any occurence in the main section is taken as the default for virtual servers. Syntax: logindumpdata [dump-string] Examples: logindumpdata Welcome/nThis server will allow %M users./n # print this when a user connects Cookie support: Yes, see 1.2.4 Default: (none) This command is exactly like logindump (1.1.2.32), except the actual data is stored in the config file instead of an external file. The format for [dump-string] is described in section 1.2.3. This directive overrides any logindump directives in the same section. 1.1.2.36 "logintries" directive Used in: virtual server sections or the main section. If virtual servers are defined, any occurence in the main section is taken as the default for virtual servers. Syntax: logintries [COUNT] Examples: logintries 10 # give 10 tries to login. logintries 1 # give only one try to login. Cookie support: No Default: logintries 3 This command limits the number of incorrect username/password combinations a connection can make before it is locked out. After this, any USER command the client will fail. This can slow down the brute forcing of passwords. 1.1.2.37 "logstrength" directive Used in: virtual server and main sections. Syntax: logstrength [VALUE] Examples: logstrength 63 # Log Everything logstrength 25 # Log bad connections, commands # resposes and generic info. Cookie support: No Default: logstrength 63 This command sets how much logging muddleftpd and/or its virtual servers will perform. It is a value created by adding up one or more of the following numbers: 1 Log connections that fail due to ipacl settings 2 Log file transfers (uploads, downloads, SITE DUMP) 4 Log command the client sends to the server. 8 Log responses to commands the client sends. 16 Log generic information, including config errors (highly recommended) 32 Log successful/unsuccessful logins and logouts of clients. So to log file transfers and generic information, use a setting of 18. 1.1.2.38 "maxconnectperip" directive Used in: virtual server sections or the main section. Syntax: maxconnectperip [COUNT] Examples: maxconnectperip 0 # set no limit maxconnectperip 2 # only 2 connections from the same # ip Cookie support: No Default: maxconnectperip This directive limits the number of logins from the same IP address to the server (or one of its virtual servers). This options will reduce the login performace of the server if it is running in standalone mode. If used in the main section, it sets the total number of connections from any one IP regardless of the virtual server the client is connected to. When used in virtual server sections, it will only affect conections to that single virtual server. 1.1.2.39 "maxspeed" directive Used in: group sections Syntax: maxspeed [BYTES-PER-SECOND] Examples: maxspeed 4096 # set max transfer speed to 4096 b/s maxspeed 1000000 # set max transfer speed to 1 Meg/sec Cookie support: Yes, see section 1.2.2. Default: (none) This directive specifies how fast a user may download/upload data at. This can be used to conserve bandwidth/annoy users. The value used is specified in bytes per second. Control port data is not affected by this command, so you may wish to also use the directive "sitecmdoff dump" when using this option. 1.1.2.40 "maxusers" directive Used in: main, vserver and group sections Syntax: maxusers [COUNT] Examples: maxusers 100 # set maximum users to 5 maxusers 0 # allow no users, hide group. Cookie support: No Default: maxusers 30 maxusers sets the maximum number of users for a server, a virtual server, or for a group. When used in the main section, maxusers will set the maximum number of users the server will allow in. Any connections that would exceed this count are immediately dropped, without any messages. When used in a virtual server section, maxusers will set the maximum number of users the server will allow to connect to that virtual server. As with the main section, connections that overflow that count will be dropped. In group sections, maxusers sets the maximum number of users that can login via that group. When that limit is reached, new connections will be given the busydump message and disconnected instead of quietly disconnected. When maxusers is set to 0 in a group section, that group will not be displayed in ftpwho listings. 1.1.2.41 "nameacl" directive Used in: group sections Syntax: nameacl [A or D]:[PATTERN] Examples: nameacl A:* # accept any username nameacl A:anonymous # accept only anonymous. nameacl D:root # deny username root. Cookie support: No Default: nameacl D:* This directive declares which usernames will be accepting when attempting to authenticate against a group. nameacl directives are checked in order, and the first one to match the username will determine the final result. If the final result is accept, than the username will continue to be authenticated against that group. If the final result is deny, muddleftpd will try the next group. 1.1.2.42 "nice" directive Used in: group sections Syntax: nice [VALUE] Examples: nice -20 # give very low priority nice 5 # give higher priority. Cookie support: Yes, see section 1.2.2. Default: nice 0 This directive sets the CPU priority of a user in a group after they have logged on. VALUE may be from -20 (highest priority) to 20 (lowest priority) with 0 being normal priority. Note that you cannot use negative values unless you run muddleftpd as root and runasuser isn't set. 1.1.2.43 "pfnaccess" directive Used in: group sections Syntax: pfnaccess [PATTERN]:[MODE] Examples: pfnaccess /b/*.mp3:NONE # no access to files with mp3 # extension in only the b dir pfnaccess /*.o:NONE # no access to object files in root # dir. pfnaccess /home/%U/*:R # give read access to all files in # user home dir and subdirs Cookie support: Yes, see section 1.2.2. Default: (none) This specifies access setting using basic regular expressions, however wildcard characters cannot match / characters, so only a single directory is affected. pfnaccess have lower priority to fnaccess, and higher priority to plain access. All the rules for fnaccess (see section 1.1.2.21) also apply to pfnaccess. 1.1.2.44 "quitdump" directive Used in: group sections Syntax: quitdump [filename] Examples: quitdump /etc/muddleftpd/BYEMSG # print this when user exits Cookie support: Yes, see 1.2.2 Default: (none) When a user quits muddleftpd, the data from the specified filename will be printed to the user as they leave. Section 1.2.4 documents cookies you can use in files specified with this directive. The file must given with a full path. 1.1.2.45 "quitdumpdata" directive Used in: group sections Syntax: quitdumpdata [dump-string] Examples: quitdumpdata Thank you/nYou downloaded %b bytes./n # print this when user exits Cookie support: Yes, see 1.2.4 Default: (none) This command is exactly like quitdump (1.1.2.40), except the actual data is stored in the config file instead of an external file. The format for [dump-string] is described in section 1.2.3. This overrides any quitdump directives in the same section. 1.1.2.46 "ratios" directive Used in: group sections. Syntax: ratios [0 or 1] Examples: ratios 1 # enable ratios. Cookie support: Yes, see section 1.2.2 Default: ratios 0 This directive specifies whether a user in a group will be subject to ratios. These ratios are specified by: byteratios (see section 1.1.2.8) fileratios (see section 1.1.2.20) initalbytes (see section 1.1.2.30) initalfiles (see section 1.1.2.31) ratiofile (see section 1.1.2.47) 1.1.2.47 "ratiofile" directive Used in: group sections, only valid if ratios is set to 1 Syntax: ratiofile [filename] Examples: ratiofile /etc/ratios ratiofile /home/rugger/ratios # location of persistant # ratios Cookie support: No Default: (none) This directive specifes that persistant ratios are to be used, and that ratio information will be stored in the given file. The given file must be specified with a full path (absolute path). This file will store what a users private ratios are and what credits (byte, file) they have. This file is in a binary format, and cannot be freely moved between differnent types of systems. Using persistant ratios also causes a signifcant performace drop in muddleftpd, since a lot of file access must occur to keep ratio data consistant. Make sure the ratio file is stored on a filesystem that isn't mounted syncronously (ie not write-back cache) otherwise performace will be terrible. 1.1.2.48 "rdnstimeout" directive Used in: main section Syntax: rdnstimeout [VALUE] Examples: rdnstimeout 0 # disable reverse lookup. rdnstimeout 10 # allow reverse lookup 10 seconds. Cookie support: No Default: rdnstimeout 15 rdnstimeout sets the amount of time muddleftpd will wait for reverse DNS lookups to occur. During this time, muddleftpd will be non-responsive. If set to 0, reverse DNS lookups will be disabled. If reverse DNS lookup fails or times out, muddleftpd will use the IP address of the host to identify it. 1.1.2.49 "realdir" directive Used in: group sections Syntax: realdir [0 or 1] Examples: realdir 0 # don't resolve symlinks. realdir 1 # resolve symlinks Cookie support: Yes, see section 1.2.2. Default: realdir 0 This specifies whether muddleftpd will attempt to resolve the real directory when a user changes to a new directory. If set, muddleftpd will resolve symlinks when changing directories if the resultant directory is within rootdir. If the user changes to a symlink that points outside of rootdir, muddleftpd will not resolve it to its real directory. 1.1.2.50 "rootdir" directive Used in: group sections Syntax: rootdir [DIRECTORY] Examples: rootdir / # set rootdir to system rootdir rootdir %r # set rootdir from auth module rootdir %h # set rootdir to users home # directory. Cookie support: Yes, see section 1.2.2. Default: rootdir %r This sets the root directory of a user in a group. rootdir must be specified with a full pathname. By default, rootdir is set by the authentication module. A user can only enter directories outside of rootdir with symlinks (use chroot to disable this). rootdir will appear to be "/" to the logged in user. 1.1.2.51 "runasuser" directive Used in: main section Syntax: runasuser [username] Examples: runasuser rugger # run as user rugger runasuser ftp # run as ftp user Cookie support: No Default: (none) runasuser instructs muddleftpd to switch to a new uid/gid specified by username after initalizing. This will prevent these things occuring in addition to things that don't work without root: 1) log rotation will not work. 2) data ports binding to port 20. 1.1.2.52 "sitecmdoff" directive Used in: group sections Syntax: sitecmdoff [CMD] Examples: sitecmdoff IDLE # disable site idle command. sitecmdoff DUMP # disable site dump command Cookie support: Yes, see 1.2.2 Default: (none) This directive selectivly disables FTP SITE commands. This can disable things like SITE ACCESS and SITE DUMP, that may improve security when using other commands. 1.1.2.53 "smartbind" directive Used in: main section Syntax: smartbind [0 or 1] Examples: smartbind 0 # use simple binding method smartbind 1 # use smart binding method Cookie support: No Default: smartbind 0 This directive instructs whether muddleftpd will take all the ports/IP's it needs to listen to and collate them to use fewer file descriptors. Set to 1 to use smart binding, 0 otherwise. For example: ftpport 21/10.1.1.1 ftpport 21/127.0.0.1 ftpport 21/10.1.1.2 With simple binding, muddleftpd will simply bind each port individually and use 3 file descriptors. With smart binding, muddleftpd will bind to all interfaces on port 21, using one file descriptor. However, connections from extra interfaces that are bound by smart binding will simply be dropped and other programs will not be able to use them. NOTE: You must set smartbind to 1 if you wish to bind to individual interfaces on most unix systems. On these unix systems, you must also set zerobind to 1 as well. 1.1.2.54 "supgid" directive Used in: group sections Syntax: supgid [SUP-GIDS] Examples: supgid %G,1 # add 1 to supgids supgid 1,2,3 # set supgids to 1, 2 and 3 supgid %G,!10 # set supgids to authentication # module, but remove group 10 supgid * # set no sup groups. Cookie support: Yes, see section 1.2.2. Default: supgid %G supgid supplies a comma separated list of supplementary groups a user will be in. Using * will cause no supplementary groups to be set. You can prefix a group number with "!" to remove any eariler occurences of that group number in the list. 1.1.2.55 "timeout" directive Used in: main, vserver and group sections Syntax: timeout [VALUE] Examples: timeout 15 # give 15 second timeout timeout 7200 # give 2 hour timeout Cookie support: Yes, but only in group sections, see section 1.2.2. Default: timeout 300 Timeout sets the amount of time the server will wait for a user response before disconnecting that user. If used in the main section or virtual server sections, timeout specifies the timeout while the user logs in. If used in a group section, it specifies the timeout after a user is logged into that group. 1.1.2.56 "uid" directive Used in: group sections Syntax: uid [VALUE or NAME] Examples: uid %u # set uid from users uid from authentication # module uid 10 # set users uid to 10 uid ftp # set the users uid to ftp. Cookie support: Yes, see section 1.2.2. Default: uid %u This directive specifies what user id a user will access/create files as. It can be speciifed either using an integer user id or a normal username. By default, the uid from the authentication module is used. If you set it to 0 (the root user), then muddleftpd will automaticly demote it to nobody's user id. 1.1.2.57 "umask" directive Used in: main, vserver and group sections Syntax: umask [OCTAL-VALUE] Examples: umask 777 # make new files with no permisions umask 666 # make new files with only execute # permissions if directories. umask 022 # make new files only writeable by # owner Cookie support: Yes, but only in group sections, see section 1.2.2. Default: (default system umask) This sets the umask used when users create files using the ftp server. When used in the main section, it sets the default for any virtual server or groups. When set in a virtual server section it sets the default for groups used by that virtual group. If used in a group section, it overrides any other setting. Umask is defined by an octal value. Users can change their umask using SITE UMASK unless the command is disabled or chmoding is set to 0. 1.1.2.58 "userjail" directive Used in: group sections Syntax: userjail [0 or 1] Examples: userjail 0 # User can relogin. userjail 1 # User cannot change username Cookie support: Yes, see section 1.2.2. Default: userjail 0 This specifies whether the user logged into a particular group can relogin as a different username without disconnecting. If set to 1, the user cannot relogin, otherwise the user will be able to use the USER command to login as a different username. This is automaticly set to 1 if droproot (see section 1.1.2.15) and/or chroot (see section 1.1.2.12) are set to 1, since not enough resources will be avaliable to change the users identity. 1.1.2.59 "vserver" directive Used in: main section. Syntax: vserver [SECTION] Examples: vserver internal # declare section internal as a # virtual server. vserver external # declare section external as a # virtual server. Cookie support: No Default: (none) This directive, if used in the main section, changes muddleftpd behaviour from being a regular server to a virtual server system. This directive is used to declare what sections in the config file are to be definitions for virtual server. By specifiing this directive multiple times in the main section, muddleftpd will declare multiple virtual servers. For more information on virtual server sections, see 1.0.2. If this directive is not used, muddleftpd assumes that main defines server information. 1.1.2.60 "welcome" directive Used in: group sections Syntax: welcome [filename] Examples: welcome /etc/muddleftpd/WELCOMEMSG # print this when user logs into a # group Cookie support: Yes, see 1.2.2 Default: (none) When a user logs into a group successfully, the data from the specified filename will be printed to the user. Section 1.2.4 documents cookies you can use in files specified with this directive. The file must given with a full path. 1.1.2.61 "welcomedumpdata" directive Used in: group sections Syntax: welcomedumpdata [dump-string] Examples: welcomedumpdata You have logged in/nThere are %N users./n # print this when user logs on. Cookie support: Yes, see 1.2.4 Default: (none) This command is exactly like welcome (see 1.1.2.60), except the actual data is stored in the config file instead of an external file. The format for [dump-string] is described in section 1.2.3. This overrides any quitdump directives in the same section. 1.1.2.62 "zerobind" directive Used in: main section, ignored if smartbind (see 1.1.2.53) is not set to 1 Syntax: zerobind [0 or 1] Examples: zerobind 0 # bind to individual interfaces zerobind 1 # always bind to all interfaces. Cookie support: No Default: zerobind 0 This is a compatiblity option for unix systems that don't support listening for connections on only one interface. If you have a BSD system, or muddleftpd is refusing to bind to the ports you specify, set zerobind and smartbind (see 1.1.2.53) to 1. 1.2 Misc references 1.2.1 Access modes [MODE] The directives that specify permissions for users when they access files are: access (see 1.1.2.1) fnaccess (see 1.1.2.21) pfnaccess (see 1.1.2.43) These require a mode string to specify what permissions a user has when a particular access line is matched. A mode string is a combination of one or more charaters, or: ALL - give all access permissions NONE - give no access permissions Letters that may make up a mode string: A - Create new filenames that don't already exist. R - Read files that already exist. L - List files (only for directories) X - Replace files that already exist. M - Create new directories. I - Remove existing directories. W - Write to existing files. H - Chmod existing files. C - allow to change to that directory. By combining these letters, any access level can be set. 1.2.2 Cookies in group sections. In group sections, cookies allow you to customize how information from the authentication module and the server is used to generate information about a new users session. Most commands valid in group sections support the use of these cookies: %U - The username the user gave the server. %v - The section name of the virtual server the user is logged into. Set to "main" if no virtual servers are defined. %V - The hostname of the virtual server the user is logged into. If no virtual servers are defined, this is set the the hostname provided by the main section, or by the machines hostname. %u - The uid of the user from the authentication module. %g - The gid of the user from the authentication module. %h - The home directory of the user from the authentication module. %r - The root directory of the user from the authentication module. %G - A comma delimited list of supplementary gids from the authentication module. Depending on the particular authentication module used, one or more of these cookies may not be set. See 2.0 for more information on authentication modules and what cookies are set by each individual one. Group directives where group section cookies are not supported: busydumpdata, byteratios, cddumpdata, fileratios, include, initalbytes, initalfiles, ipacl, maxusers, nameacl, quitdumpdata, ratiofile, welcomdumpdata. Group directives where group section cookies are avaliable, but only cookies not derived from the authentication module. authuser, and any directives which are used by the authentication module currently selected. 1.2.3 Specifing a string for busydumpdata, cddumpdata, welcomedumpdata and quitdumpdata. To use these directives, a string must be specified on a single line describing what to dump onto the screen. To get over the limitation, you can use control characters to perform tabs, insert spaces, and move to the next line. Note that all the control characters are specified with a / prefix, not a \. All uses of \ result in the following character being quoted exactly before the / are resolved: eg: \/\n is the same as /n and will be resolved to a newline. Control characters that are valid are: /n - Goto the next line. /s - Insert a space. You need this if you need spaces at the beginning or end of the directive. /t - Insert a tab. // - Insert a regular forward slash The strings specified for the dumpdata directives may also contain cookies specified in 1.2.4. Examples: cddumpdata You are now in %C/nYou have %a credits left would result in the following output (for chdir /) 250-You are now in / You have 1000000 credits left 250 "/" is the current directory. busydumpdata /s/s/sThe server is full./n Please try again later/nBye! would result in the following output (on login to a full group) 421- The server is full. Please try again later Bye! 421 Too many users. Cannot login. 1.2.4 Cookies in dumped files. When you specify a file to be dumped onto the screen, or set a string to be dumped on the screen, the following cookies can be inserted into that string or file to use information the server has internally: %T - current date and time %U - username of the user connecting. set to before login. %C - Current working directory, relitive to a user's root directory. Only avaliable after user is logged in. %E - The email address set in the configuration file. (See 1.1.2.14 for more info) %M - The maximum number of users that may exist in the current virtual server the user is connected to, or main server (before login) or maxiumun number of users a group can allow in. %N - The number of users currently in a group just after the user has logged in. It is not set before login. %L - The hostname of the server. Can be overridden. (see 1.1.2.28 for more information) %R - The hostname of the client obtained by reverse host lookup. %f - The number of files a user has downloaded. %F - The number of files a user has uploaded. %b - The number of bytes the user has downloaded in file transfers. %B - The number of bytes the user has uploaded in file transfers. %I - The number of bytes the user has downloaded in listings. %i - The number of listings the user has performed. %D - The total number of bytes the user has downloaded over data connections. %t - The total number of bytes the user has transfered over data connections (both upload and downloads) %c - The total number of data transfers the user has made. (for listing, downloads and uploads) %d - The total number of data transfers the user has made for downloading (listing and downloading) %v - The section name of the virtual server the user is connected to (or main if no virtual servers are declared) If the user is using ratios, the following are also avaliable. %a - The number of download byte credits a user has. %A - The number of download file credits a user has. 2.0 Authentication modules 2.0.1 Overview. Muddleftpd uses authentication modules to determine the following: - whether a user will be authenticated within a particular group. - is the username and password the user supplied correct. - what parameters are associated with that user (home directory, uid, gid, ...) Authentication modules under muddleftpd come in two flavours: - Static modules. These modules are already compiled into muddleftpd and can be accessed using a keyword for the authmethod. These modules are documented in 2.1 - Dynamic modules. These modules are not built with muddleftpd, but are dynamicly linked in while muddleftpd is authenticating an user. These are distributed separately from muddleftpd, and don't require muddleftpd to be recompiled to use. They can even be added while muddleftpd is still running. All modules are able to probe the configuration file for settings. They will often add several configuration options of their own, and the following cookies will work on them: %U - The username the user gave the server. %v - The section name of the virtual server the user is logged into. Set to "main" if no virtual servers are defined. %V - The hostname of the virtual server the user is logged into. If no virtual servers are defined, this is set the the hostname provided by the main section, or by the machines hostname. When a module has finished, the following cookies may be used on other options (see 1.2.2 for more info). Each individual module may or may provide information to set the following cookies: %u - The uid of the user. %g - The gid of the user. %h - The home directory of the user. %r - The root directory of the user. %G - A comma delimited list of supplementary gids for the user. You must check the documentation for the particular module you are going to use as to whether these options are set. 2.1 Static modules in muddleftpd The following modules are compiled into muddleftpd. 2.1.1 "unix" authentication module. This authentication module authenticates using the unix system passwords. It will automaticly detect shadow passwords and use them. It fully supports account and password expiry with shadow passwords. It requires root access to authenticate against shadow password files. To use this module in a group section, set the following directive: authmethod unix The following options may also be set in the same group section to configure the "unix" module: unix_passwdtype This forces what type of passwords are used by the module. If set to normal, shadow passwords will never be used. If set to shadow, normal passwords will never be acceped. All cookies described in 2.0 are set by the unix authentication module. The unix module will affect group selection by accepting any user found in the password file and authenticated them. If the user is not found in the password file, authentication will continue to the next group. Note: If muddleftpd is compiled when shadow passwords are not installed, and you wish to use shadow passwords, you will need to compile muddleftpd again after installing shadow passwords to enable the use of shadow passwords. 2.1.2 "anonymous" authentication module. The anonymous authentication module will authenticate users for anonymous access to the server. It will accept any username, using any password. It will log the password the user uses. The usernames this module will accept can be limited using the nameacl directive (see 1.1.2.41). Any users authenticated by this module will access files as user nobody in group nogroup. The module will set the users root directory to the home directory of the user "ftp". The users home directory will be set to /. To use this module in a group section, set the following directive: authmethod anonymous These directives can be used to tune the anonymous module: anonymous_user This changes the user muddleftpd probes to determine the root directory for the anonymous user. By default it is the user "ftp" This module will set all cookies described in 2.0 except for the suplementary groups cookie(%G) This module affects group selection by accepting all usernames presented to the module. You can limit what usernames it accepts by using the nameacl directive. However, if the username specified in anonymous_user (or "ftp" if anonymous_user isn't specified) cannot be read the module will cancel authentication. 2.1.3 "internal" authentication module. This module will use a separate password file in muddleftpd's own format to authenticate users. It is designed to provide password protection for authentication when users don't need an associated uid/gid. The password file consistes of one or more lines with the following format, one user per line. :: eg: rugger NvAdfesdaesEr:/home/rugger/:/ These password files may be modified using the external program mudpasswd. See mudpasswd.txt for more information on this program. To use the internal module, set the following directive in the relevent group section: authmethod internal The following directives may be set to configure the internal password module: internal_passfile This sets the path to the password file that the internal authentication module will read passwords and user info from. This file must be owned by the user running the server and must not be group or world writable, otherwise the module will refuse to use it. The internal authentication module will set the root directory (%r) and home directory (%h) cookies only. This module affects group selection by accepting any usernames defined in the given password file. If it isn't defined in the password file, the user is then passed onto the next group. If the password file cannot be loaded, or the password file is not safe, then authentication of the user is cancelled. Note: If the users in the separate password file map to the users in the main password file, and you want each user to use their own uid, you can set: uid %U to accomplish this. 2.1.4 "disabled" authentication module This built in module will cancel the authentication of anyone passed to the module. You need to use nameacl to restrict what usernames get canceled by this module. To use the disabled module in a group, use the following directive in that group: authmethod disabled This module does not set any of the cookies described in 2.0.1 This module affects group selection by canceling any username it is allowed to authenticate. 2.1.5 "pam" authentication module. This module allows muddleftpd to authenticate using PAM and PAM modules. This module also uses the password file to determine the session information the user will have. PAM is useful for systems where password encryption is not provided by regular crypt. To use the pam module, set the following directive in the relevent group sections: authmethod pam 3.0 FTP commands. 3.1 Non-site commands.