Difference between revisions of "Using the fileServersNG Docker Images"

From FileSys.Org Wiki
 
(2 intermediate revisions by the same user not shown)
Line 245: Line 245:
 
|FSNG_SMB_DEBUGFLAGS
 
|FSNG_SMB_DEBUGFLAGS
 
|smb.sessionDebug
 
|smb.sessionDebug
|Enable SMB server debug output with a comma delimited list of debug levels. See the Configuring JFileServer document for a list of the available debug flag names
+
|Enable SMB server debug output with a comma delimited list of debug levels. See the [http://www.filesys.org/wiki/index.php/Configuring_JFileServer#The_.3CsessionDebug.3E_Configuration_Setting Configuring JFileServer] document for a list of the available debug flag names
 
|Negotiate,Socket,State
 
|Negotiate,Socket,State
 
|-
 
|-
Line 290: Line 290:
 
|FSNG_FTP_DEBUGFLAGS
 
|FSNG_FTP_DEBUGFLAGS
 
|ftp.sessionDebug
 
|ftp.sessionDebug
|Enable FTP server debug output with a comma delimited list of debug levels. See the Configuring JFileServer document for a list of the available debug flag names
+
|Enable FTP server debug output with a comma delimited list of debug levels. See the [http://www.filesys.org/wiki/index.php/Configuring_JFileServer#FTP_Server_Configuration Configuring JFileServer] document for a list of the available debug flag names
|File,Search,Error,DataPort,Directory
+
|File,Search,Error
 
|}
 
|}
  
 +
To use the environment variables to configure fileServersNG add entries to the ''docker-compose.yml'' file, eg.
 +
 +
version: "3.4"
 +
 +
services:
 +
    fileserversng-v61-share:
 +
    ...
 +
 +
    fileserversng-v61-acs:
 +
        image: filesysorg/alfresco-fileserversng-v61:latest
 +
        environment:
 +
            FSNG_SMB_DIALECTS: SMB2,SMB3
 +
            FSNG_FTP_ENABLE: "true"
 +
        ports:
 +
            - "8080:8080"
 +
            - "445:445"
 +
            - "21:21"
 +
            - "60000:60100"
 +
        volumes:
 +
            - fileserversng-v61-acs-volume:/usr/local/tomcat/alf_data
 +
        depends_on:
 +
            - fileserversng-v61-postgres
 +
 +
    fileserversng-v61-postgres:
 +
    ...   
 +
 +
=== Configuring Kerberos/AD Authentication For The SMB Server ===
 +
The fileServersNG-v61 Docker image can be configured to use Kerberos authentication for the SMB server. This is the most secure authentication available for the SMB server, and also provides single sign-on from Active Directory clients.
 +
 +
The first part of the Kerberos/AD authentication setup requires an account to be setup for the SMB server service, and a service principal name mapping to be created for the service. Follow steps 1 and 2 of the main [http://www.filesys.org/wiki/index.php/Configuring_Kerberos/AD_Authentication_For_The_SMB_Server Kerberos/AD Authentication Setup] document.
 +
 +
The fileServersNG-v61 Docker image has already configured the Java VM to look for a login configuration file in the ''/usr/local/tomcat/kerberos'' folder, with a login configuration file name of ''alfresco-login.config''. The same folder is also used to hold the Kerberos client configuration file, ''krb5.conf'', and the keytab that was generated on the Active Directory server when following steps 1 and 2 of the Kerberos/AD Authentication Setup document.
 +
 +
Create a folder on the host system to hold the Kerberos configuration, Java login configuration and keytab files. Copy the keytab file into the new folder, and name it ''jfileserver.keytab''.
 +
 +
Create the Java login configuration file named ''alfresco-login.config'' in the Kerberos configuration folder. Using a text editor add the following text to the file substituting your host (where the Docker image is being run from) and domain names :-
 +
 +
FileServerSMB {
 +
  com.sun.security.auth.module.Krb5LoginModule required
 +
  debug=false
 +
  storeKey=true
 +
  useKeyTab=true
 +
  keyTab="/usr/local/tomcat/kerberos/jfileserver.keytab"
 +
  principal="cifs/<host>.<domain>";
 +
};
 +
 +
Note: Be careful not to use Tab characters in the Java login configuration file.
 +
 +
Create the Kerberos configuration file in the Kerberos configuration folder. Using a text editor add the following text to the file substituting your AD server, domain and realm names :-
 +
 +
[libdefaults]
 +
default_realm=<REALM>
 +
 +
[realms]
 +
<REALM> = {
 +
  kdc = <AD-Server-Name>.<domain>
 +
  admin_server = <AD-Server-Name>.<domain>
 +
}
 +
 +
[domain-realm]
 +
<domain> = <REALM>
 +
.<domain> = <REALM>
 +
 +
Finally, we need to modify the ''docker-compose.yml'' to enable Kerberos authentication and map the Kerberos configuration folder to the Docker folder using a volume mapping. Using a text editor modify the ''fileserversng-v61-acs'' service section to add the ''FSNG_KERBEROS_REALM'' environment variable setting, and the volume mapping for the ''/usr/local/tomcat/kerberos'' folder :-
 +
 +
    fileserversng-v61-acs:
 +
        image: filesysorg/alfresco-fileserversng-v61:latest
 +
        environment:
 +
            FSNG_SMB_KERBEROS_REALM: <REALM>
 +
        ports:
 +
            - "8080:8080"
 +
            - "445:445"
 +
            - "21:21"
 +
            - "60000:60100"
 +
        volumes:
 +
            - fileserversng-v61-acs-volume:/usr/local/tomcat/alf_data
 +
            - <Local-path-to-the-Kerberos-configuration-folder>:/usr/local/tomcat/kerberos
 +
        depends_on:
 +
            - fileserversng-v61-postgres
 +
 +
Note: Be careful not to use Tab characters in the ''docker-compose.yml'' file.
 +
 +
If you have problems getting the Kerberos/AD authentication to initialise successfully you can try using the ''debug=true'' setting in the Java login configuration file, and set the ''FSNG_SMB_KERBEROS_DEBUG: "true"'' environment variable in the ''docker-compose.yml'' file.
 +
 
== Accessing the fileServersNG SMB Server On Windows ==
 
== Accessing the fileServersNG SMB Server On Windows ==
 
To use the fileServersNG Docker image to run an SMB server on Windows requires some additional work to access the SMB server. A Windows host uses the native SMB port 445 to run a local file server as well as to access various services such as remote registry editing, access to the event log manager and service manager and many other functions. When running the fileServersNG Docker image on Windows we cannot map the native SMB port 445 from the Docker container to the host system as the port will already be in use. Instead we need to setup a network route to the Docker VM that is running the JFileServer image.
 
To use the fileServersNG Docker image to run an SMB server on Windows requires some additional work to access the SMB server. A Windows host uses the native SMB port 445 to run a local file server as well as to access various services such as remote registry editing, access to the event log manager and service manager and many other functions. When running the fileServersNG Docker image on Windows we cannot map the native SMB port 445 from the Docker container to the host system as the port will already be in use. Instead we need to setup a network route to the Docker VM that is running the JFileServer image.

Latest revision as of 14:04, 20 June 2019

The following Docker images are available that contain Alfresco server installations with the fileServersNG file servers subsystem deployed. The Docker images include a free to use licence for 25 clients, licence keys for larger number of clients can be purchased from filesys.org :-

Image Description
filesysorg/alfresco-fileserversng-v5 Alfresco 5.2 server with the fileServersNG subsystem deployed, using an embedded PostGreSQL database server, includes Share
filesysorg/alfresco-fileserversng-v6 Alfresco 6.0 server with the fileServersNG subsystem deployed, for use in a multi-container setup via docker-compose

fileServersNG v5

The fileServersNG-v5 add-on is designed to work with Alfresco v5.x, and should also work with Alfresco v4.x.

The Docker image will be downloaded when you use the docker run command, if it is not already available on your system, or you can download the image using docker pull <image-name>.

The Docker images expose a web server on port 8080 and the JFileServer SMB server on port 445. The Alfresco web interface is available at http://localhost:8080/alfresco and the Share web interface is available at http://localhost:8080/share/. There is an administrators account with user name admin password admin.

Configuring The fileServersNG V5 Docker Image

The fileServersNG Docker image can be configured using a combination of volume mapping and environment variables. Volume mapping is required to persist the Alfresco server state when the container is stopped or removed. Environment variables are used to configure the fileServerNG subsystem.

Using Volume Mapping

The fileServerNG Docker image needs a number of paths mapping to the host system in order to persist the Alfresco state when the container is stopped/removed. This can be done by either mapping Docker image paths to host paths or using Docker volumes that are created using the command :-

docker volume create name

The following volume mappings are available :-

Image Path Description
/content The main Alfresco content store with the raw data files
/alfresco/alf_data The Alfresco database data tables, key store and SOLR data
/alfresco/tomcat/logs The Tomcat server logs including catalina.out
/alfresco/tomcat/shared/classes/license Location of the JFileServer licence file, required to enable the JFileServer Enterprise features

In the following examples where a host path is shown a Docker volume name could be used instead.

To run the fileServersNG Docker image with the Alfresco state persisted to folders on the host system, with local folders of /AlfrescoDocker/content, /AlfrescoDocker/alf_data and /AlfrescoDocker/logs :-

docker run -d --rm --name fsng -p 8080:8080 -p 445:445 -v /AlfrescoDocker/content:/content -v /AlfrescoDocker/alf_data:/alfresco/alf_data -v /AlfrescoDocker/logs:/alfresco/tomcat/logs
 filesysorg/alfresco-fileserversng-v5:latest

You should be able to monitor the Alfresco server startup via the catalina.out log file in the local folder, for example :-

tail -f /AlfrescoDocker/logs/catalina.out

The fileServersNG Docker image includes the JFileServer Enterprise code, a trial key is included. If you have your own JFileServer Enterprise key you will need to map an additional local folder that contains the jfileserver.lic licence file :-

docker run -d --rm --name fsng -p 8080:8080 -p 445:445 -v /AlfrescoDocker/content:/content -v /AlfrescoDocker/alf_data:/alfresco/alf_data -v /AlfrescoDocker/logs:/alfresco/tomcat/logs
 -v /AlfrescoDocker/licence:/alfresco/tomcat/shared/classes/license filesysorg/alfresco-fileserversng-v5:latest

Using Environment Variables

The default configuration can be overridden using environment variables. As Alfresco fileServersNG is running in a Docker container it can use the privileged ports for the various file servers. The SMB server will use TCP port 445, the FTP server will use port 21 by default.

The following environment variables are used :-

Variable Name Description Default Value
FSNG_SMB_ENABLE Enable the SMB server true
FSNG_FTP_ENABLE Enable the FTP server false
FSNG_NFS_ENABLE Enable the NFS server false
FSNG_SMB_DIALECTS SMB dialects that the SMB server will negotiate SMB2
JFSRV_SMB_DEBUGFLAGS SMB debug flags Negotiate,Socket,State
JFSRV_FTP_PORT Port that the FTP server listens on 21
JFSRV_FTP_DEBUGFLAGS FTP debug flags File,Search,Error,DataPort,Directory
JFSRV_NFS_DEBUGFLAGS NFS debug flags File,FileIO
FSNG_LICENCE_PATH Relative path of the JFileServer licence folder on the classpath /license

To run fileServersNG SMB server with the SMB2 protocol enabled via the JFileServer Enterprise add-on, use the following :-

 docker run -d --rm --name fsng -p 8080:8080 -p 445:445 -v /AlfrescoDocker/content:/content -v /AlfrescoDocker/alf_data:/alfresco/alf_data -v /AlfrescoDocker/logs:/alfresco/tomcat/logs
  -e FSNG_SMB_DIALECTS=SMB2 filesysorg/alfresco-fileserversng-v5:latest

If you have your own JFileServer Enterprise licence you will need to add the volume mapping to the local folder that contains the jfileserver.lic licence file, for example -v /AlfrescoDocker/licence:/alfresco/tomcat/shared/classes/license.

fileServersNG v6

The fileServersNG-v6 add-on is designed to work with Alfresco v6.0, which uses the new containerised setup.

To run the Alfresco v6.0 setup use the following docker-compose.yml file. To start the Alfresco server use docker-compose up, to stop the server use <Ctrl-C> and then docker-compose down.

The Docker image will be downloaded when you use the docker-compose up command, if it is not already available on your system, or you can download the image using docker pull <image-name>.

The Docker images expose a web server on port 8080 and the JFileServer SMB server on port 445. The Alfresco web interface is available at http://localhost:8080/alfresco and the Share web interface is available at http://localhost:8080/share/. There is an administrators account with user name admin password admin.

Configuring The fileServersNG V6 Docker Image

The default configuration can be overridden using properties. As Alfresco fileServersNG is running in a Docker container it can use the privileged ports for the various file servers. The SMB server will use TCP port 445, the FTP server will use port 21 by default.

The properties can be set via the docker-compose.yml file or by updating the alfresco-global.properties file in the Docker image. The default docker-compose.yml has the following configuration for the Alfresco service :-

services:
   alfresco:
       image: filesysorg/alfresco-fileserversng-v6
       environment:
           JAVA_OPTS : "
               -Ddb.driver=org.postgresql.Driver
               -Ddb.username=alfresco
               -Ddb.password=alfresco
               -Ddb.url=jdbc:postgresql://postgres:5432/alfresco
               -Dsolr.host=solr6
               -Dsolr.port=8983
               -Dsolr.secureComms=none
               -Dsolr.base.url=/solr
               -Dindex.subsystem.name=solr6
               -Dshare.host=localhost
               -Ddeployment.method=DOCKER_COMPOSE
               -Dcsrf.filter.enabled=false
               -Dsmb.enabled=true
               -Dftpng.enabled=false
               "
       ports:
           - 8082:8080 #Browser port
           - 445:445 # SMB server
           - 21:21   # FTP server

The properties are set via the JAVA_OPTS environment variable. By default the SMB server is enabled (via -Dsmb.enabled=true) and the FTP server is disabled (via -Dftpng.enabled=false).

The following properties are available :-

Property Name Description Default Value
smb.enabled Enable the SMB server true
ftpng.enabled Enable the FTP server false
smb.dialects SMB dialects that the SMB server will negotiate SMB2
smb.tcpipSMB.port Port that the SMB server listens on 445
smb.sessionDebug SMB debug flags Socket
ftp.port Port that the FTP server listens on 21
ftp.sessionDebug FTP debug flags File,Search,Error,DataPort,Directory

fileServersNG v6.1

The fileServersNG-v61 add-on is designed to work with Alfresco v6.1, which uses the new containerised setup.

To run the Alfresco v6.1 setup use the following docker-compose.yml file. To start the Alfresco server use docker-compose up, to stop the server use <Ctrl-C> and then docker-compose down.

The Docker image will be downloaded when you use the docker-compose up command, if it is not already available on your system, or you can download the image using docker pull <image-name>.

The Docker images expose a web server on port 8080, the JFileServer SMB server on port 445 and JFileServer FTP server on port 21, with a block of data ports configured at 60000-60100. The Alfresco web interface is available at http://localhost:8080/alfresco and the Share web interface is available at http://localhost:8080/share/. There is an administrators account with user name admin password admin.

Configuring The fileServersNG V6.1 Docker Image

The default configuration can be overridden using properties. As Alfresco fileServersNG is running in a Docker container it can use the privileged ports for the various file servers. The SMB server will use TCP port 445, the FTP server will use port 21 by default.

The properties can be set via environment variables in the docker-compose.yml file or by updating the alfresco-global.properties file in the Docker image.

Here is the list of available environment variables with their associated property names :-

Variable Name Property Name Description Default Value
FSNG_SMB_ENABLE smb.enable Enable the SMB server true
FSNG_FTP_ENABLE ftp.enable Enable the FTP server false
FSNG_NFS_ENABLE nfs.enable Enable the NFS server false
FSNG_SMB_DIALECTS smb.dialects SMB dialects that the SMB server will negotiate. A comma delimited list of values with SMB1, SMB2 and/or SMB3 SMB2
FSNG_SMB_DEBUGFLAGS smb.sessionDebug Enable SMB server debug output with a comma delimited list of debug levels. See the Configuring JFileServer document for a list of the available debug flag names Negotiate,Socket,State
FSNG_SMB_KERBEROS_REALM smb.kerberos.realm Enables Kerberos authentication for the SMB server using the specified Kerberos realm
FSNG_SMB_KERBEROS_STRIPUSERNAMESUFFIX smb.kerberos.stripUsernameSuffix When enabled the Kerberos logon username will have the realm stripped to use the simpler username to match to an existing Alfresco account name true
FSNG_SMB_KERBEROS_DEBUG smb.kerberos.debug Enable debug output from the Java JAAS APIs, equivalent of setting the system properties sun.security.jgss.debug and sun.security.krb5.debug to true false
FSNG_SMB_LOGIN_ENTRY smb.kerberos.loginEntryName Java JAAS login entry name used by the SMB server for the Kerberos service logon FileServerSMB
FSNG_SMB_DISABLE_NTLM smb.disableNTLM Disable NTLM logons, Kerberos authentication must be enabled false
FSNG_SMB_DISALLOW_NTLMv1 smb.disallowNTLMv1 Disallow the weaker NTLM v1 logons when NTLM logons are enabled true
FSNG_SMB_USE_SPNEGO smb.useSPNEGO Use Simple Protected Negotiation for authentication. The default authentication will use NTLMSSP when NTLM logons are enabled. If Kerberos authentication is enabled then SPNEGO will be selected automatically. false
FSNG_FTP_PORT ftp.port Port that the FTP server listens for incoming connections on 21
FSNG_FTP_DEBUGFLAGS ftp.sessionDebug Enable FTP server debug output with a comma delimited list of debug levels. See the Configuring JFileServer document for a list of the available debug flag names File,Search,Error

To use the environment variables to configure fileServersNG add entries to the docker-compose.yml file, eg.

version: "3.4"

services:
   fileserversng-v61-share:
   ...

   fileserversng-v61-acs:
       image: filesysorg/alfresco-fileserversng-v61:latest
       environment:
           FSNG_SMB_DIALECTS: SMB2,SMB3
           FSNG_FTP_ENABLE: "true"
       ports:
           - "8080:8080"
           - "445:445"
           - "21:21"
           - "60000:60100"
       volumes:
           - fileserversng-v61-acs-volume:/usr/local/tomcat/alf_data
       depends_on:
           - fileserversng-v61-postgres

   fileserversng-v61-postgres:
   ...    

Configuring Kerberos/AD Authentication For The SMB Server

The fileServersNG-v61 Docker image can be configured to use Kerberos authentication for the SMB server. This is the most secure authentication available for the SMB server, and also provides single sign-on from Active Directory clients.

The first part of the Kerberos/AD authentication setup requires an account to be setup for the SMB server service, and a service principal name mapping to be created for the service. Follow steps 1 and 2 of the main Kerberos/AD Authentication Setup document.

The fileServersNG-v61 Docker image has already configured the Java VM to look for a login configuration file in the /usr/local/tomcat/kerberos folder, with a login configuration file name of alfresco-login.config. The same folder is also used to hold the Kerberos client configuration file, krb5.conf, and the keytab that was generated on the Active Directory server when following steps 1 and 2 of the Kerberos/AD Authentication Setup document.

Create a folder on the host system to hold the Kerberos configuration, Java login configuration and keytab files. Copy the keytab file into the new folder, and name it jfileserver.keytab.

Create the Java login configuration file named alfresco-login.config in the Kerberos configuration folder. Using a text editor add the following text to the file substituting your host (where the Docker image is being run from) and domain names :-

FileServerSMB {
 com.sun.security.auth.module.Krb5LoginModule required
 debug=false
 storeKey=true
 useKeyTab=true
 keyTab="/usr/local/tomcat/kerberos/jfileserver.keytab"
 principal="cifs/<host>.<domain>";
};

Note: Be careful not to use Tab characters in the Java login configuration file.

Create the Kerberos configuration file in the Kerberos configuration folder. Using a text editor add the following text to the file substituting your AD server, domain and realm names :-

[libdefaults]
default_realm=<REALM>

[realms]
<REALM> = {
  kdc = <AD-Server-Name>.<domain>
  admin_server = <AD-Server-Name>.<domain>
}

[domain-realm]
<domain> = <REALM>
.<domain> = <REALM>

Finally, we need to modify the docker-compose.yml to enable Kerberos authentication and map the Kerberos configuration folder to the Docker folder using a volume mapping. Using a text editor modify the fileserversng-v61-acs service section to add the FSNG_KERBEROS_REALM environment variable setting, and the volume mapping for the /usr/local/tomcat/kerberos folder :-

   fileserversng-v61-acs:
       image: filesysorg/alfresco-fileserversng-v61:latest
       environment:
           FSNG_SMB_KERBEROS_REALM: <REALM>
       ports:
           - "8080:8080"
           - "445:445"
           - "21:21"
           - "60000:60100"
       volumes:
           - fileserversng-v61-acs-volume:/usr/local/tomcat/alf_data
           - <Local-path-to-the-Kerberos-configuration-folder>:/usr/local/tomcat/kerberos
       depends_on:
           - fileserversng-v61-postgres

Note: Be careful not to use Tab characters in the docker-compose.yml file.

If you have problems getting the Kerberos/AD authentication to initialise successfully you can try using the debug=true setting in the Java login configuration file, and set the FSNG_SMB_KERBEROS_DEBUG: "true" environment variable in the docker-compose.yml file.

Accessing the fileServersNG SMB Server On Windows

To use the fileServersNG Docker image to run an SMB server on Windows requires some additional work to access the SMB server. A Windows host uses the native SMB port 445 to run a local file server as well as to access various services such as remote registry editing, access to the event log manager and service manager and many other functions. When running the fileServersNG Docker image on Windows we cannot map the native SMB port 445 from the Docker container to the host system as the port will already be in use. Instead we need to setup a network route to the Docker VM that is running the JFileServer image.

To setup a network route to the JFileServer Docker container :-

  • Get the Docker VM IP address using :-
docker-machine ip default
  • Start the fileServersNG container without a port mapping for the SMB server port using :-
docker run -d --rm --name fsng -p 8080:8080 -v /AlfrescoDocker/content:/content -v /AlfrescoDocker/alf_data:/alfresco/alf_data -v /AlfrescoDocker/logs:/alfresco/tomcat/logs
 filesysorg/alfresco-fileserversng-v5:latest
  • Get the IP address of the fileServersNG container using :-
docker inspect fsng | findstr IPAddress
  • Add network routing to the fileServerNG container :-
route add /P <container-network-IP> MASK 255.0.0.0 <docker-machine-IP>

For example if the container IP address is 172.17.0.2 and the Docker machine IP is 192.168.99.100 the routing command would be

route add /P 172.0.0.0 MASK 255.0.0.0 192.168.99.100
  • Map a network drive from the Windows host using a UNC path of \\<docker-machine-IP>\alfresco using the admin user name password, or a normal user account if you have added users to the Alfresco system.