Configuring JFileServer

From FileSys.Org Wiki
Revision as of 13:12, 3 August 2022 by Tommygonk (talk | contribs)

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>
    <servers>...</servers>
    <SMB>...</SMB>
    <FTP>...</FTP>
    <NFS>...</NFS>
    <shares>...</shares>
    <debug>...</debug>
    <security>...</security>
    <licence>...</licence>
    <server-core...</server-core>
</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>

    <requireSigning/>
    <disableEncryption/>

    <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 <requireSigning/> configuration setting indicates that the server will only accept SMB2 connections that have signing enabled. It is only currently relevant when the SMB2 dialect is enabled.

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 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 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/>
    <KerberosConfig>...</KerberosConfig>
    <LoginConfig>...</LoginConfig>
</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 <KerberosConfig> setting allows a JFileServer specific Kerberos configuration file to be used. The setting takes the full path to the Kerberos configuration file. This is the equivalent of using the Java property java.security.krb5.conf.

The <LoginConfig> setting allows a JFileServer specific Java login configuration file to be used without editing the global Java security settings file. The setting takes the full path to the login configuration file. This is the equivalent of using the Java property java.security.auth.login.config.

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"/>

SMB2/SMB3 Configuration

There are SMB2 and SMB3 specific configuration values within the <server-core> configuration section, which is separate to the <SMB> configuration section.

The <server-core> configuration section has the following syntax, all settings are optional :- 

<server-core>
    <SMB2>
        <maxPacketSize>2M</maxPacketSize>
        <requireSigning/>
    </SMB2>
    <SMB3>
        <encryptionTypes>CCM,GCM</encryptionTypes>
        <disableEncryption/>
        <useAESProvider>SunJCE</useAESProvider>
    </SMB3>
</server-core>

The <SMB2> <maxPacketSize> setting sets the maximum packet size that the server will negotiate with the client. The value can be specified as 'nM' for megabytes, or 'nK' for kilobytes or as the number of bytes. Most clients will use a value between 2 to 8 megabytes.

The <SMB2> <requireSigning/> setting forces clients to use SMB2 signing. If the client does not support SMB2 signing the session connection will be rejected.

The <SMB3> <encryptionTypes> value specifies which SMB3 encryption types are enabled, and the preferred order. The valid values are 'GCM' for AES/GCM/128 bit and 'CCM' for AES/CCM/128 bit.

The <SMB3> <disableEncryption/> setting will allow an SMB3 connection without encryption to be established with the server.

The <SMB3> <useAESProvider> setting is used to specify the name of the JCE provider that will be used by the AES/GCM/128 bit encryption mode. Using a value of 'SunJCE' will use the Sun/Oracle/OpenJDK hardware accelerated implementation. The default setting will use the BouncyCastle JCE provider which only provides a software based implementation of the AES/GCM cipher.

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

Shares Configuration

The <shares> configuration section is used to define the virtual filesystems that are available to the various protocol servers.

A virtual filesystem requires a driver class that implements the core filesystem interface, plus optional interfaces for advanced features.

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

<shares>
    <diskshare name="..." comment="...">
        <driver>
            <class>...</class>
            ...
        </driver>
    </diskshare>

    <diskshare name-"..." comment="...">
    ...
    </diskshare>
    ...
</shares>

Multiple virtual filesystems can be defined each using a seperate <diskshare> configuration section. The virtual filesystems can use different driver classes. Each driver class can have its own set of configuration items. Each <diskshare> definition must have a unique name, and can have an optional comment.

There are a number of virtual filesystems included in the JFileServer jar file. The org.filesys.smb.server.disk.JavaNIODiskDriver virtual filesystem uses the Java I/O classes to create a network filesystem that is mapped to a folder on the local filesystem.

JavaNIODiskDriver Configuration

The <driver> configuration section for the org.filesys.smb.server.disk.JavaNIODiskDriver virtual filesystem has the following syntax :- 

<driver>
    <class>org.filesys.smb.server.disk.JavaNIODiskDriver</class>
    <LocalPath>...</LocalPath>

    <LargeFileSize>...</LargeFileSize>
    <TrashcanPath>...</TrashcanPath>
    <Debug/>
</driver>

The <LocalPath> setting specifies the local path of the folder to be shared, the folder must exist. The path may be an absolute path or a relative path, for example a path of ./.

The <LargeFileSize> setting specifies the file size where file delete and truncate operations are performed using a background thread to help with server response. The file size can be specified as bytes, or nK for kilobytes, nM for megabytes, nG for gigabytes.

The <TrashCanPath> setting specifies the folder to be used for background delete of large files. The path must be on the same physical volume as the folder specified by <LocalPath> as files are renamed into the trashcan folder where they will then be deleted via a background thread.

The <Debug/> setting enables debug output for this instance of the virtual filesystem driver.

Debug Configuration

The <debug> configuration section is used to define how debug output is handled and where it is sent to. The <debug> configuration section has the following syntax :- 

<debug>
    <output type="Console|File|JDK">
        <class>...</class>
        ...
    </output>
</debug>

The following pre-defined debug output types are available for the type="..." value :-

  • Console
    Output to the console
  • File
    Output to the file defined by the <logfile>...</logfile> parameter. An optional <append/> parameter can be specified to append to an existing log file.
  • JDK
    Use Java JDK logging, use the <Properties>...</Properties> parameter to specify the location of the logging properties file.

It is also possible to provide your own custom debug output class by implementing the org.filesys.debug.DebugInterface interface. You would then use the <class>...</class> setting to specify the debug class, and not use the type="..." setting. Any parameters defined within the <output> section will be passed to the debug interface implementation initialize() method.

Security Configuration

The <security> configuration section is used to define the JCE provider for the file server and to define server users when using local authentication.

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

<security>
    <JCEProvider>...</JCEProvider>

    <users>
        <user name="...">
            <password>...</password>
            <md4>...</md4>

            <administrator/>
            <comment>...</comment>
            <realname>...</realname>
            <home>...</home>
        </user>
    </users>
</security>

The <JCEProvider> setting specifies the class that provides standard encryption support that the file server requires. The default setting is to use the BouncyCastle JCE provider library via the class org.bouncycastle.jce.provider.BouncyCastleProvider.

The <users> section defines local user accounts on the file server when local authentication is being used. If you are using Kerberos authentication the list of users will be ignored.

The <user> section defines a local user, the name="..." value is required and must be unique within the list of user names. The <password>...<password> setting species the user password in plaintext or you can specify the password using the MD4 value via a hex-ASCII value.

The optional <home>...</home> setting specifies the local path of the users home folder.

Licence Configuration

To use the JFileServer Enterprise features a licence is required, this is configured via the <licence> configuration section.

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

<licence>
    <licenceKey>...</licenceKey>

    <licencePath>...</licencePath>
</licence>

To specify a licence key that is embedded within the server configuration file use the <licenceKey>...</licenceKey> configuration section, the licence key text can be split onto multiple lines.

To specify a licence key that is in an external file use the <licencePath>.../<licencePath> configuration section with the full path to the licence file.

Retrieved from "http://filesys.org/wiki/index.php?title=Configuring_JFileServer&oldid=208"