## ProFTPD module `mod_ls`

The `mod_ls` module handles the `LIST`, `NLST`, and `STAT` FTP commands.

## Directives

- DirFakeGroup
- DirFakeMode
- DirFakeUser
- ListOptions
- ListStyle
- ShowSymlinks
- UseGlobbing

### DirFakeGroup

Syntax: DirFakeGroup off|on [display-name]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`, .ftpaccess
Module: mod_ls
Compatibility: All versions

The `DirFakeGroup` directive can be used to hide the true group ownership of files (including directories, FIFOs, etc) in directory listings. If simply turned on, `DirFakeGroup` will display all files as being owned by group "ftp". Optionally, the display-name parameter can be used to specify a group other than "ftp". A display-name of "~" can be used as the parameter, in order to display the primary group name of the current user.

Both `DirFakeGroup` and `DirFakeUser` are completely cosmetic; the display-names configured do not need to exist on the system, and neither directive affects permissions, real ownership or access control in any way.

### DirFakeMode

Syntax: DirFakeMode display-mode
Default: None
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`, .ftpaccess
Module: mod_ls
Compatibility: All versions

The `DirFakeMode` directive configures the mode (or permissions) which will be displayed for all files and directories in directory listings. For each subset of permissions (i.e. user, group, other), the "execute" permission for directories is added in listings if the "read" permission is specified by this directive.

As with `DirFakeUser`, and `DirFakeGroup`, the "fake" permissions shown in directory listings are cosmetic only; they do not affect real permissions or access control in any way on the server. Note, however, that `DirFakeMode` can affect the real permissions, for example, for FTP mirroring tools. Such tools tend to create a mirror from what the tool sees (e.g. `DirFakeMode` permissions) on the source FTP server.

Examples:

      # Display everything as read-only
      DirFakeMode 0444

### DirFakeUser

Syntax: DirFakeUser off|on [display-name]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`, .ftpaccess
Module: mod_ls
Compatibility: All versions

The `DirFakeUser` directive can be used to hide the true user ownership of files (including directories, FIFOs, etc) in directory listings. If simply turned on, `DirFakeUser` will display all files as being owned by user "ftp". Optionally, the display-name parameter can be used to specify a user other than "ftp". A display-name parameter of "~" can be used in order to display the name of the current user.

Both `DirFakeGroup` and `DirFakeUser` are completely cosmetic; the display-names specified do not need to exist on the system, and neither directive affects permissions, real ownership or access control in any way.

### ListOptions

Syntax: ListOptions options [strict [maxdepth depth] [maxfiles count] [maxdirs count] [LISTOnly] [NLSTOnly] [NoErrorIfAbsent] [AdjustedSymlinks] [SortedNLST]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`, .ftpaccess
Module: mod_ls
Compatibility: 1.2.8rc1 and later

The `ListOptions` directive is used to configure various optional behavior of `mod_ls`. Note: all of the configured `ListOptions` parameters must appear on the same line in the configuration; only the first `ListOptions` directive that appears in the configuration is used.

The currently supported flags are:

- `LISTOnly`

  This flag tells `mod_ls` to apply the `ListOptions` configuration only to FTP `LIST` commands, and not to e.g. `NLST`/`STAT` commands.

- `NLSTOnly`

  This flag tells `mod_ls` to apply the `ListOptions` configuration only to FTP `NLST` commands, and not to e.g. `LIST`/`STAT` commands.

- `NoErrorIfAbsent`

  This flag tells `mod_ls` to return the FTP 226 response code for `LIST`/`NLST` commands for files/paths which do not exist, rather than returning the 450 error code.

- `AdjustedSymlinks`

  This flag tells `mod_ls` to try to automatically adjust any symlink destination paths when the FTP session is chrooted, so that the adjusted symlinks work properly e.g. for FTP clients.

  Note that this flag first appeared in `proftpd-1.3.7rc1`.

- `SortedNLST`

  By default, `mod_ls` returns `NLST` results in an unordered list, i.e. the sort order used by the underlying filesystem and the `readdir(3)` library function. Some FTP clients, however, may want/expect to have `NLST` results sorted alphabetically. Use this flag to achieve that sorted `NLST` behavior.

  Note that this flag first appeared in `proftpd-1.3.6rc3`.

See also: ListOptions

### ListStyle

Syntax: ListStyle Unix|Windows
Default: `ListStyle Unix`
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_ls
Compatibility: 1.3.8rc1 and later

The `ListStyle` directive can be used to emit Windows-style directory listings for the `LIST` command, rather than default Unix-style directory listings. This is mainly to support certain FTP clients which only expect/support the Windows-style listings. For example, using:

      ListStyle Windows

leads to a directory listing like this, for the basic command-line `ftp(1)` Unix client:

      ftp> ls
      229 Entering Extended Passive Mode (|||57644|)
      150 Opening ASCII mode data connection for file list
      11-30-15  07:29PM       <DIR>          a_folder
      11-30-15  07:29PM                   16 file
      226 Transfer complete

### ShowSymlinks

Syntax: ShowSymlinks on|off
Default: `ShowSymlinks on`
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_ls
Compatibility: All versions

The `ShowSymlinks` directive configures whether symbolic links are displayed as such in directory listings, or whether they are not displayed to the client. If `ShowSymlinks` is off, then the linked file's permissions and ownership are used in the directory listing.

### UseGlobbing

Syntax: UseGlobbing on|off
Default: `UseGlobbing on`
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_ls
Compatibility: 1.2.5rc1 and later

The `UseGlobbing` directive controls the use of `glob(3)` functionality, which is needed for supporting wildcard characters such as "*" in directory listing requests from FTP clients.

The `glob(3)` functionality in FTP servers has been knowwn to cause security issues (see CVE-2001-0249), thus should be disabled when not needed.

Examples:

      # Turn off support for globs in LIST/NLST commands
      UseGlobbing off

## Installation

The `mod_ls`module is always installed.

Frequently Asked Questions

Question: I have a legacy FTP application which sends the `NLST` command, and expects to receive only file names, without any directory prefix (relative or absolute). I cannot change this application. How can I configure ProFTPD to return only names for the `NLST` command?
Answer: You can use the `ListOptions` directive to achieve this, like so:

      # We want only names, no hidden files, and only for NLST
      ListOptions '-A -1 NLSTOnly'

© Copyright 2000-2020 The ProFTPD Project
All Rights Reserved