OpenCms documentation
OpenCms documentation

Network share access

It is possible to provide access to the virtual file system of OpenCms via the SMB / CIFS protocol, which is used natively by Microsoft Windows for accessing and providing so-called “network shares”. It is possible to mount such network shares so that they appear as a normal file system on the client machine, both under Windows and Linux. OpenCms uses the JLAN library for this functionality.

Once the network share access has been set up, network shares can be accessed via the path syntax \\HOSTNAME\SHARENAME (standard Windows syntax) or smb://HOSTNAME/SHARENAME (most other clients).

When using one of the provided share configurations on your local OpenCms installation, the network share is available at \\localhost\OPENCMS (or smb://localhost/OPENCMS).

To use the network share feature, you need to configure both the general server settings for the JLAN library, as well as the individual network shares which should be provided by OpenCms. If either no shares are configured, or no JLAN server configuration is present, the network share server thread will not be started.

The JLAN server configuration should be located in your OpenCms web application folder at  WEB-INF/config/jlanConfig.xml. This guide does not describe the format of this configuration files, since the format is defined by the JLAN library and documented, for example, in the JLAN server installation guide. There are two example configuration files for Linux and Windows (jlanConfig.xml.linux and jlanConfig.xml.windows) under WEB-INF/config, so you can just copy the right file for your operating system to jlanConfig.xml.

The node /jlanserver/SMB/host/tcpipSMB is used to set the port used by the SMB-over-TCP/IP interface:

<tcpipSMB port="1445" platforms="linux,macosx,solaris" />

If no port is given, the standard SMB port (445) will be used. The reason to a port other than 445 is that in some operating systems, e.g., Linux, programs not running under the “root” user do not have the required permissions to listen on port numbers < 1025 by default. This is why the port is set to 1445 in the example configuration jlanConfig.xml.linux.

Using a non-standard port (such as 1445) for SMB is possible but may cause difficulties especially with Microsoft Windows and other clients expecting the standard port 445. We therefore recommend configuring your OpenCms server to allow the use of the standard port 445. There are several ways to do this, depending on your server configuration. For example, you may use tools like socat or iptables to forward port 445 to the port you are using. For a Debian/Ubuntu based Linux server running Tomcat 7 we recommend using authbind as described below.

If you use a Debian based Linux distribution such as Ubuntu running Tomcat 7, setting up the required permissions for OpenCms to allow SMB acess using port 445 can be done easily with authbind. This is a package specifically designed to allow certain users access to otherwise restricted ports. To allow the user tomcat7 to bind to port 445 for SMB do this:

1:# apt-get install authbind

2:# touch /etc/authbind/byport/445

3:# chown tomcat7:tomcat7 /etc/authbind/byport/445

4:# chmod 755 /etc/authbind/byport/445

5:# sed -i "s/#AUTHBIND=no/AUTHBIND=yes/" /etc/default/tomcat7

Basically this first installs the authbind package (line 1), then creates an exception allowing the user tomcat7 to bind to port 445 (lines 2-4) , and finally configures Tomcat to run with authbind (line 5). After you have done this restart Tomcat and check the log file catalina.out. If you find a line [SMB] Waiting for new connection ... your network share configuration is working.

It is possible to configure the OpenCms folders shared over SMB directly in jlanConfig.xml, but we recommend configuring these in opencms-importexport.xml, as described below.

To use SMB network shares on an OpenCms server running on Windows XP, using NetBIOS may be required. Please refer to the JLAN server installation guide for information about setting up NetBIOS in this case.

Each network share is described by one repository entry in opencms-importexport.xml under the <repositories>-node, in the following form:

<repository name="OPENCMS" class="org.opencms.jlan.CmsJlanRepository">
  <params>
    <param name="project">Offline</param>
    <param name="root">/</param>
    <param name="addBOM">false</param>
    <param name="wrapper">
      org.opencms.file.wrapper.CmsResourceWrapperReplaceDeleted
    </param>
    <param name="wrapper">
      org.opencms.file.wrapper.CmsResourceWrapperPropertyFile
    </param>
    <param name="wrapper">
      org.opencms.file.wrapper.CmsResourceWrapperModules
    </param>
  </params>
</repository>

The name given in the name-attribute will be used as the name of the share which you can connect to, e.g., //servername/OPENCMS for the configuration given above. The class attribute must be set to org.opencms.jlan.CmsJlanRepository.

The behavior of the network share can be configured with the following parameters:

project (required)

The name of the project which should be used for VFS operations.

root (required)

The root path of the folder which should be the root folder of the network share. In the above configuration, the root folder / is configured, which means the network share can be used to access the whole VFS including the system folder (at least if the user connecting to the share has appropriate permissions).

addBOM (optional)

A Boolean value which is used to configure whether byte order marks should be added to plaintext resources by the repository.

wrapper (optional)

This parameter can be used to configure zero or more resource wrappers. Resource wrappers are classes which can add special features to the network share file system. The only two wrappers we currently recommend are:

  • org.opencms.file.wrapper.CmsResourceWrapperPropertyFile: Since CIFS/SMB has no concept of file types or properties, this resource wrapper adds “virtual” files which can be used to edit the properties or resource type of a VFS resource. For example, if a file is located at /folder/file.txt, there will be a special file /folder/__properties/file.txt.properties which, when edited, will save the properties of file.txt.
  • org.opencms.file.wrapper.CmsResourceWrapperReplaceDeleted: CIFS/SMB can’t distinguish between a file in OpenCms which has been deleted and published and one which has been deleted, but not published. This wrapper is used so that when the user tries to create a file, but a file with the same path has been deleted and not published, the old file will be automatically replaced with the new one.
  • org.opencms.file.wrapper.CmsResourceWrapperModules: If the wrapper is present, module management (import, export and deletion) via the network share is enabled. The share will provide special folders under /modules/ that allow you to manage modules. See here for more information.

The OpenCms network share access uses the JLAN Enterprise authenticator, which should work with both NTLMv1 and NTLMv2 authentication. Users can use their normal OpenCms accounts to log in to the network shares. Please note that users need to have logged in at least once normally to the OpenCms workplace before they can log in to a network share, since the network share code uses a different password hash type, and the password hash for network share access is only saved when the user logs in to the workplace.

The user will not be able to connect to a share if they do not have “View” permissions for the root folder configured for that share, even if their user name and password are correct. Users will also not be able to see files for which they lack “View” permissions over a network share connection.

The CIFS / SMB protocol has no support for file types, properties, or publishing. It also lacks direct support for copying and moving files. When creating files via network share access, the appropriate resource type is determined via the file extension mappings in opencms-vfs.xml.  This means copying (which is just done by creating a new file and copying the contents of the old file to the new one) may not preserve the resource type if there is no unique file extension mapping for the type, and will not preserve properties or other metadata.

CIFS / SMB only works reasonably fast on a low-latency network, so we do not recommend using it over the internet or other high-latency connections.

When you install OpenCms locally and you want to access it (in the default JLan configuration) via \\localhost\OPENCMS (Windows) or smb://localhost/OPENCMS (Linux, MacOS), you typically only have to rename the config file jLanConfig.xml.windows or jLanConfig.xml.linux to jLanConfig.xml. But you typically will encounter some additional problems.

  • On Windows 7: The port 445 used to provide the share is already blocked by a service named "server". Go to "Control Panel" -> "Administrative Tools" -> "Services". Stop the service "server" and change (therefore right-click the service and choose "Properties" from the context menu) the "Starttype" to "disabled". Then restart Windows. Afterwards you should be able to connect to \\localhost\OPENCMS (using a valid OpenCms account, e.g., the user "Admin" with password "admin" in a default installation.
  • On Linux: You may need to map the port 1445, at which the share is exposed back to port 445. You may use a tool like "socat" for that task and mount the VFS similar as done in the script below (that should be run as root)
#!/bin/bash
socat TCP-LISTEN:445,fork TCP:localhost:1445 &
mount -t cifs //localhost/OPENCMS ~/opencms/vfs -o credentials=~/.credentials/occredentials,rw,uid=1000,gid=1000
# Set CIFS/SMBv1 explicitly if you get a `mount error(112): Host is down`:
mount -t cifs //localhost/OPENCMS ~/opencms/vfs -o credentials=~/.credentials/occredentials,rw,uid=1000,gid=1000,vers=1.0
  • On MacOS: Mounting may work fine out of the box. Here's an example on how you could mount the VFS:
mkdir /Volumes/opencms
mount_smbfs -d 777 //Admin@localhost:1445/OPENCMS /Volumes/opencms