Configuring JFileServer

The JFileServer file server is configured using a simple XML file, the same configuration format is used by the Enterprise version of the file server.

The configuration is contained within the <fileserver> main section with various sub-sections to configure which file server protocols are enabled, configuration for each protocol, security and debug logging. Here's an overview of the XML configuration file :-

<fileserver>
    <server>...</server>
    <SMB>...</SMB>
    <FTP>...</FTP>
    <NFS>...</NFS>
    <shares>...</shares>
    <debug>...</debug>
    <security>...</security>
    <licence>...</licence>
</fileserver>

Environment variables may be used in attributes and values within the XML configuration using the syntax '${env-var-name}'.

Some configuration settings allow an optional platforms="..." attribute, this allows a configuration to be used on multiple platforms. If the current platform that the JFileServer is running on is not listed in the platforms="..." list then the setting will be ignored.

The available platform values are Windows, Linux, MacOSX and Solaris. The platforms value is a comma delimited list of valid platforms for the current setting.

The <server> configuration section is used to enable or disable which file server protocols are available. The syntax has changed from the JLAN configuration as each protocol now has an enable="true|false" attribute, this makes it easier to use an environment variable to control whether a particular file server protocol is enabled.

The <servers> configuration section has the following syntax :-

<servers>
    <SMB enable="true|false">
    <FTP enable="true|false">
    <NFS enable="true|false">
 </servers>

SMB Server Configuration

The <SMB> configuration section is used to configure the SMB protocol server that allows a drive or mount to be mapped to the JFileServer file server which can then be accessed as if it were a local drive on the client system.

The <SMB> configuration section has the following syntax :-

<SMB>
    <host>
        <broadcast>...</broadcast>
        <smbdialects>...</smbdialects>
        <comment>...</comment>
        <netBIOSSMB .../>
        <tcpipSMB .../>
        <hostAnnounce .../>
    </host>
    <authenticator ...>
        ...
    </authenticator>
    <sessionDebug .../>
 </SMB>

Note: The JLAN XML configuration has <Win32NetBIOS/> and <Win32Announce/> configuration options, these are currently ignored by JFileServer as the Win32 NetBIOS legacy code has been moved out into a seperate add-on project. With most clients using native SMB connections on port 445, and SMB2/SMB3 connections requiring native SMB connections, there are only a small number of special cases where the Win32 NetBIOS interface is of use.

The <host> Configuration Section

The <host> sub-section contains the main networking and protocol configuration settings.

The <broadcast> setting specifies the network broadcast mask that is required to send broadcast datagrams, used by the NetBIOS protocol and host announcement. JFileServer now accepts the setting of 'AUTO' where the broadcast mask will be determined automatically. In some cases this may not work, you will then need to specify the broadcast mask. For eample if your network addresses are in the 192.168.1.x/8 range the broadcast mask would be 192.168.1.255.

The <smbdialects> setting configures which SMB dialects the file server will negotiate with a client. The value should be a comma delimited list of dialect names. The high level dialect names available are SMB1 for the standard server, plus SMB2 and SMB3 for the Enterprise server.

The <comment> setting provides a comment that is visible to clients when displaying the server properties.

The <netBIOSSMB .../> setting configures the SMB file server to use the TCPIP socket based NetBIOS protocol. The default setting of <netBIOSSMB/> will enable the TCPIP NetBIOS interface using TCP port 139 and UDP ports 137 and 138. These settings can be overridden using the sessionPort="...", namingPort="..." and datagramPort="..." attributes. For example, if running the JFileServer on a linux or Mac system as a normal user the server will not be able to bind the privileged ports 137/138/139, so we may use the following configuration and use firewall rules to forward the network traffic to the unprivileged ports :-

<netBIOSSMB sessionPort="1139" namingPort="1137" datagramPort="1138"/>

An optional platforms="..." attribute may be used for the NetBIOS SMB setting.

The <tcpipSMB> setting configures the SMB file server to use the native SMB socket based protocol. The default setting of <tcpipSMB/> will enable the native SMB interface using TCP port 445. This setting can be overridden using the port="..." attribute. For example, if running the JFileServer on a linux or Mac system as a normal user the server will not be able to bind the privileged port 445, so we may use the following configuration and use firewall rules to forward the network traffic to the unprivileged port :-

<tcpipSMB port="1445"/>

An optional platforms="..." attribute may be used for the TCPIP SMB setting.

The <hostAnnounce .../> setting is used to enable the TCPIP NetBIOS host announcer that periodically broadcasts the server details to the local network. This allows the server to show up in the local network list or workgroup.

The default host announcement is broadcast every minute, the announcement interval can be set using the optional interval="..." attribute.

The <authenticator> Configuration Section

The <authenticator type="..."> section configures how the SMB server handles user authentication. The optional type="..." attribute can have the values "enterprise" or "local", or it is possible to specify your own authenticator class. The enterprise authenticator setting provides the latest authentication methods such as NTLMv2 and Kerberos via the NTLMSSP and SPNEGO mechanisms. The local authenticator setting provides support for older LanMan and NTLMv1 authentication, these are considered to be insecure these days so it is recommended to use the "enterprise" setting.

For the "enterprise" setting the authenticator configuration has the following syntax :-

<authenticator type="enterprise">
    <disableNTLM/>
    <useSPNEGO/>
    <disallowNTLMv1>
               
    <-- Kerberos related settings -->
    <Realm>...</Realm>
    <Password>...</Password>
    <LoginEntry>...</LoginEntry>
    <kerberosDebug/>
</authenticator>

By default the Enterprise authenticator enables NTLM logons, either NTLMv1 or NTLMv2. To only allow the more secure NTLMv2 logons use the <disallowNTLMv1> configuration setting.

To enable Kerberos logons to the SMB file server the <Realm>, <Password> and <LoginEntry> values are required. The <Realm> setting should contain the Kerberos realm, usually the domain name in uppercase. The <Password> setting is used to access the server Kerberos setup. The <LoginEntry> setting specifies the Java JAAS login entry name to use for the SMB server service logon, the default value is FileServerSMB.

The <kerberosDebug/> setting is a convenience setting that enables various Java debug output levels by setting the required properties.

The <useSPNEGO/> setting enables the use of SPNEGO (Simple Protected NEGOtiation) as well as the default NTLMSSP. If you have enabled Kerberos logons then SPNEGO will be enabled automatically.

The <sessionDebug> Configuration Setting

The <sessionDebug flags="..."/> setting is used to enable SMB server debug output. The flags="..." value is a comma delimited list of debug output level names from the following list :-

Flag	Description
PKTTYPE	Received packet type
STATE	Session state changes
RXDATA	Dump received data packet
TXDATA	Dump sent packet data
DUMPDATA	Dump data packets
NEGOTIATE	Protocol negotiate phase
TREE	Tree connection/disconnection
SEARCH	File/directory searches
INFO	File/directory information requests
FILE	File open/close/information requests
FILEIO	File read/write
TRAN	SMB transactions
ECHO	Echo requests
ERROR	Errors returned to the client
IPC	IPC$ named pipe requests
LOCK	Lock/unlock requests
DCERPC	DCE/RPC request processing
STATECACHE	File state cache
TIMING	Time packet processing
NOTIFY	Asynchronous change notifications
STREAMS	NTFS streams handling
SOCKET	Socket connections
PKTPOOL	Memory pool allocate/release
PKTSTATS	Memory pool statistics
THREADPOOL	Thread pool handling
BENCHMARK	Benchmarking requests
OPLOCK	Opportunistic lock handling
PKTALLOC	Memory pool handling
COMPOUND	Compound request handling (Enterprise only)
CANCEL	Cancel request handling (Enterprise only)
SIGNING	Packet signing (Enterprise only)
ENCRYPTION	Encryption handling (Enterprise only)

For example, to enable SMB server debug output to help with logon and connection issues you could use the following setting :-

<sessionDebug flags="Negotiate,Socket,State,Error"/>

FTP Server Configuration

The <FTP> configuration section is used to configure the FTP protocol server that allows a client to connect using any FTP client application. A standard FTP connection sends plaintext commands, and details including username and password, so it is recommended to use FTPS so that the commands are sent over an encrypted SSL connection.

The <FTP> configuration section has the following syntax :-

<FTP>
    <port>...</port>
    <allowAnonymous/>
    <debug .../>
           
    <keyStore>...</keyStore>
    <keyStoreType>...</keyStoreType>
    <keyStorePassphrase>...</keyStorePassphrase>
           
    <trustStore>...</trustStore>
    <trustStoreType>...</trustStoreType>
    <trustStorePassphrase>...</trustStorePassphrase>
          
    <requireSecureSession>
    <sslEngineDebug/>
</FTP>

The <port> setting defines the port that the FTP server will listen for connections on, if not specified the default FTP port of 21 will be used. If running the JFileServer file server as a normal user on a linux or Mac system you will need to use a non-privileged port, 1024 or above.

The <allowAnonymous/> setting specifies that anonymous guest logons are allowed to the FTP server.

The <debug flags="..."/> setting is used to enable FTP server debug output. The flags="..." value is a comma delimited list of debug output level names from the following list :-

Flag	Description
STATE	Session state changes
RXDATA	Dump received data packet
TXDATA	Dump sent packet data
DUMPDATA	Dump data packets
SEARCH	File/directory searches
INFO	Information requests
FILE	File open/close/information requests
FILEIO	File read/write requests
ERROR	Errors sent back to the client
PKTTYPE	Received packet type
TIMING	Time packet processing
DATAPORT	Data port handling
DIRECTORY	Directory commands
SSL	Secure sessions

FTPS Server Configuration

The FTP server allows connections to switch into secure SSL mode after connecting to the configured FTP server port.

To enable FTPS we need to create a keystore and truststore for the SSL connections. To create a keystore using the JKS format keystore type use the following commands, filling in the required details when prompted :-

$ keytool -genkeypair -alias jfsftp -keyalg RSA -keystore FTPSKeyStore
               
Enter keystore password: 
Re-enter new password:
What is your first and last name?
[Unknown]: Your Name
What is the name of your organizational unit?
[Unknown]: OrgUnit
What is the name of your organization?
[Unknown]: Company
What is the name of your City or Locality?
[Unknown]: City
What is the name of your State or Province?
[Unknown]: Province
What is the two-letter country code for this unit?
[Unknown]: CC
Is CN=You Name, OU=OrgUnit, O=Company, L=City, ST=Province, C=CC correct?
[no]:yes

Enter key password for <client>
(RETURN if same as keystore password): 
Re-enter new password:

To generate the truststore use the following commands :-

$ keytool -export -alias jfsftp -keystore FTPSKeyStore -rfc -file FTPS.cer
$ keytool -import FTPSCert -file FTPS.cer -keystore FTPSTrustStore

You can now fill in the JFileServer configuration to enable FTPS :-

<keyStore>/path/to/FTPSKeyStore</keyStore>
<keyStoreType>JKS</keyStoreType>
<keyStorePassphrase>keystore-password</keyStorePassphrase>

<trustStore>/path/to/FTPSTrustStore</trustStore>
<trustStoreType>JKS</trustStoreType>
<trustStorePassphrase>truststore-password</trustStorePassphrase>

The <requireSecureSession/> configuration setting will only allow connections that use the FTP SSL mode to logon.

The <sslEngineDebug/> setting is used to enable additional debug output from the Java JSSE SSL session processing.

NFS Server Configuration

The <NFS> configuration section is used to configure the NFS protocol server that allows a client to mount a JFileServer filesystem which can then be accessed as if it were on a local drive on the client system.

The <NFS> configuration section has the following syntax :-

<NFS>
    <enablePortMapper/>
    <disablePortMapperRegistration/>
    <PortMapperPort>...</PortMapperPort>
    <MountServerPort>...</MountServerPort>
    <NFSServerPort>...</NFSServerPort>
    <RPCRegisterPort>...</RPCRegisterPort>
    <rpcAuthenticator>
        ...
    </rpcAuthenticator>
    <debug .../>
    <mountServerDebug/>
    <portMapperDebug/>
    <FileCache>...</FileCache>
    <fileCacheDebug/>
</NFS>

TODO: NFS configuration settings