File Server Subsystem 3.2

From alfrescowiki

Jump to: navigation, search


Contents

Introduction

This page replaces the articles below. Please refer to these if configuring the file servers in Alfresco versions prior to 3.2:

For versions > 3.4 please refer to File Server Subsystem_4.0

The File Server Subsystem allows access to the Alfresco data stores through the SMB/CIFS, FTP and NFS protocols. This allows you to browse to the server using Windows Explorer or create a Network Place, for example. As with any other Alfresco Subsystem, the File Server Subsytem exposes all of its configuration options as properties that can easily be controlled through one of the mechanisms described in Configuring Subsystems. The sections that follow describe each of the configurable properties supported by the File Server Subsystem, and for development/debugging purposes some advanced configuration changes that can be made through Spring bean definition overrides.

SMB/CIFS Server Configuration

The server includes Java socket based implementations of the SMB/CIFS protocol that can be used on any platform. The server can listen for SMB traffic over the TCP protocol (native SMB), supported by Windows 2000 and later versions, and the NetBIOS over TCP (NBT) protocol, supported by all Windows versions. There is also a Windows specific interface that uses Win32 NetBIOS API calls via JNI code. This allows the Alfresco CIFS server to run alongside the native Windows file server.

The default configuration will use the JNI based code under Windows and the Java socket based code under Linux, Solaris and Mac OS X.

Configuration

The following properties can be configured for the SMB/CIFS server. See Configuring Subsystems.

cifs.enabled
Enables or disables the CIFS server.
cifs.serverName
Specifies the host name for the Alfresco CIFS server. This can be a maximum of 16 characters and must be unique on the network. The special token {localname} can be used in place of the local server's host name and a unique name can be generated by prepending/appending to it.
cifs.domain
An optional property. When non-empty, specifies the domain or workgroup that the server belongs to. This defaults to the domain/workgroup of the server if not specified.
cifs.hostannounce
Enables announcement of the CIFS server to the local domain/workgroup so that it shows up in Network Places/Network Neighborhood.
cifs.sessionTimeout
Specifies the CIFS session timeout value in seconds. The default session timeout is 15 minutes. If no I/O occurs on the session within this time then the session will be closed by the server. Windows clients send keep-alive requests, usually within 15 minutes.

Java-based SMB

Unless enabled on Windows via advanced Spring bean definition overrides (see below), the following properties will only take effect on non-Windows servers, where the Java-based SMB implementation is used.

cifs.broadcast
Specifies the broadcast mask for the network.
cifs.bindto
Specifies the network adapter to bind to. If not specified the server will bind to all available adapters/addresses.
cifs.tcpipSMB.port
Controls the port used to listen for the SMB over TCP/IP protocol (or native SMB), supported by Win2000 and above clients. The default port is 445.
cifs.ipv6.enabled
Enables the use of IP v6 in addition to IP v4 for native SMB. When true, the server will listen for incoming connections on IPv6 and IPv4 sockets.
cifs.netBIOSSMB.namePort
Controls the NetBIOS name server port to listen on. The default is 137.
cifs.netBIOSSMB.datagramPort
Controls the NetBIOS datagram port. The default is 138.
cifs.netBIOSSMB.sessionPort
Controls the NetBIOS session port to listen on for incoming session requests. The default is 139.
cifs.WINS.autoDetectEnabled
When true causes the cifs.WINS.primary and cifs.WINS.secondary properties to be ignored.
cifs.WINS.primary
Specifies a primary WINS server to register the server name with.
cifs.WINS.secondary
Specifies a secondary WINS server to register the server name with.
cifs.disableNIO
Disables the new NIO based CIFS server code and reverts to using the older socket based code.

Windows Native SMB

The following property will only take effect on Windows servers, where by default a JNI-based CIFS implementation is in use.

cifs.disableNativeCode
When true, switches off the use of any JNI calls and JNI based CIFS implementations.

Running alfresco CIFS on a windows server running windows CIFS

It is more involved to setup alfresco cifs on a windows server than on a Linux server. This is because generally a Linux server does not have any cifs service running before the installation of alfresco whereas a windows server will typically already have its own cifs service running.

For the Netbios protocol, Windows layer can be a front-end layer: a Netbios request sent to the windows server will be redirected by the windows layer to the windows file service or to the alfresco file service, depending on the name sent with the request. The alfresco JNI code allows alfresco Netbios to run while Windows Netbios runs.

However, for native SMB, the JNI there is no alfresco JNI code. That means that alfresco needs to bind to a network interface to its port 445. That means that you have either to deactivate windows native cifs (port 445) or block using a firewall traffic to port 445, or create a virtual network interface and bind alfresco to it. The best solution depends on the version of the OS. See paragraphs Turning off windows native SMB and Turning off windows native SMB on Vista And Windows 2008 for fore information.

Running SMB/CIFS from a normal user account

On Unix-like systems such as linux, Solaris, Mac OS X, the default Alfresco setup must be run using the root user account so that the CIFS server can bind to the privileged ports (TCP 139/445 UDP 137/138). The CIFS server can be configured to run using non-privileged ports and then use firewall rules to forward requests from the privileged ports to the non-privileged ports.

To configure the CIFS server to use non-privileged ports use the following property settings (See Configuring Subsystems).

cifs.tcpipSMB.port=1445
cifs.netBIOSSMB.namePort=1137
cifs.netBIOSSMB.datagramPort=1138
cifs.netBIOSSMB.sessionPort=1139

Other port numbers can be used but must be above 1024 to be in the non-privileged range.

The firewall rules should then be set up to forward requests on TCP ports 139/445 to TCP 1139/1445 and UDP ports 137/138 to UDP 1137/1138.

On Mac OS X the following commands can be used - also refer to installing on Mac OS X:

sysctl -w net.inet.ip.fw.enable=1
sysctl -w net.inet.ip.forwarding=1
sysctl -w net.inet.ip.fw.verbose=1
sysctl -w net.inet.ip.fw.debug=0
ipfw flush
ipfw add 100 allow ip from any to any via lo0
# Forward native SMB and NetBIOS sessions to non-privileged ports
ipfw add 200 fwd <local-ip>,1445 tcp from any to me dst-port 445
ipfw add 300 fwd <local-ip>,1139 tcp from any to me dst-port 139
# Forward NetBIOS datagrams to non-privileged ports (does not currently work)
ipfw add 400 fwd <local-ip>,1137 udp from any to me dst-port 137
ipfw add 500 fwd <local-ip>,1138 udp from any to me dst-port 138

Replace '<local-ip>' with the IP address of the server that Alfresco is running on.

On Linux, the following commands can be used to get started, but be aware these commands will delete all existing firewall and NAT rules and could be a security risk:

echo 1 > /proc/sys/net/ipv4/ip_forward
modprobe iptable_nat
iptables -F
iptables -t nat -F
iptables -P INPUT ACCEPT
iptables -P FORWARD ACCEPT
iptables -P OUTPUT ACCEPT
iptables -t nat -A PREROUTING -p tcp --dport 445 -j REDIRECT --to-ports 1445
iptables -t nat -A PREROUTING -p tcp --dport 139 -j REDIRECT --to-ports 1139
iptables -t nat -A PREROUTING -p udp --dport 137 -j REDIRECT --to-ports 1137
iptables -t nat -A PREROUTING -p udp --dport 138 -j REDIRECT --to-ports 1138

For some reason the UDP forwarding does not seem to work, this affects the NetBIOS name lookups. To get around the problem you can either add a DNS entry matching the CIFS server name and/or add a static WINS mapping, or add an entry to the clients LMHOSTS file.

On Solaris 10, ipfilter can be used out of the box:

  • make sure that your NAT box will forward IP packets using routeadm
  • setup the redirection rules in /etc/ipf/ipnat.conf
rdr nge0 192.168.244.25/32 port 445 -> 192.168.244.25 port 1445
rdr nge0 192.168.244.25/32 port 137 -> 192.168.244.25 port 1137
rdr nge0 192.168.244.25/32 port 138 -> 192.168.244.25 port 1138
rdr nge0 192.168.244.25/32 port 139 -> 192.168.244.25 port 1139
  • enable packet filtering for the interface type you're using by uncommenting the appropriate line(s) in /etc/ipf/pfil.ap
  • start the IP filter services:
$ svcadm restart network/pfil
$ svcadm restart ipfilter
$ ipnat -l

More info @ http://www.obfuscation.org/ipf/ipf-howto.html

Advanced Spring Overrides

CIFS server beans

The SMB/CIFS server beans are declared in the file-servers-context.xml file in WEB-INF/classes/alfresco/subsystems/fileServers/default/file-servers-context.xml. Using the subsystem extension classpath mechanism, site specific customisation of these default values can be placed in a Spring bean file in /tomcat/shared/classes/alfresco/extension/subsystems/fileServers/default/default/custom-file-servers-context.xml (note that the default/default part of the path is intentional).

The main bean that drives the CIFS server configuration is called cifsServerConfig. This has several properties that can be populated with 'child' beans that control various optional SMB implementations

The three SMB implementations
tcpipSMB
Controls the Java-based SMB over TCP/IP implementation, compatible with Windows 2000 clients and later
netBIOSSMB
Controls the Java-based NetBIOS over TCP/IP implementation, compatible with all Windows clients
win32NetBIOS
Controls the JNI-based NetBIOS over TCP/IP implementation, only enabled for Alfresco servers running on Windows

When one of the above properties is not set, it deactives support for the corresponding protocol implementation.

The platforms property

The tcpipSMB and netBIOSSMB beans have a platforms property that allow their configuration to be targeted to Alfresco servers running on specific platforms. The property is formatted as a comma-separated list of platform IDs. Valid platform IDs are windows, linux, solaris, macosx and aix.

Java socket code in Windows

For detailed instructions, see Running Java socket code on Windows.

To run the native SMB over TCP/IP protocol (port 445) under Windows 2003 one possible method is to disable Windows from using the port by editing, or creating, the following registry key:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\NetBT\Parameters]
 "SMBDeviceEnabled"=dword:00000000

To enable the Java socket based NetBIOS implementation (ports 137, 138, 139) under Windows requires that NetBIOS is disabled on one or all network adapters. This can be done via the Network Connections control panel in the advanced TCP/IP properties for each adapter.

Other bean controls

The serverComment of the cifsServerConfig bean controls the comment that is displayed in various Windows information dialogs.

CIFS server debug flags

The sessionDebugFlags property of the cifsServerConfig bean enables debug output levels for CIFS server debugging. The value should be in the form of a comma-separated list of the flag names in the table below.

CIFS server debug flags
Flag Description
NetBIOS NetBIOS layer
State Session state changes
Tree Filesystem connection/disconnection
Search Folder searches
Info File information requests
File File open/close
FileIO File read/write
Tran Transaction requests
Echo Echo requests
Errors Responses returning an error status
IPC IPC$ named pipe
Lock File byte range lock/unlock
Pkttype Received packet type
Dcerpc DCE/RPC requests
Statecache File state caching
Notify Change notifications
Streams NTFS streams
Socket NetBIOS/native SMB socket connections
PktPool Memory pool allocations/de-allocations
PktStats Memory pool statistics dumped at server shutdown
ThreadPool Thread pool

Those flags will effectively out the debug information in the log files only if the log4j configuration instructions below are followed.

CIFS server log4j configuration

The log4j.properties file must also have SMB/CIFS protocol debug output enabled using:

log4j.logger.org.alfresco.smb.protocol=debug

The following logging level must also be enabled to log debug output from the core file server code:

log4j.logger.org.alfresco.fileserver=debug

Running Java socket code on Windows

A default Linux install will use the Java CIFS socket code. A default Windows install will use the JNI CIFS code. (Note that you have two JNI api: winsock and netbios. On 64bit Windows the Winsock NetBIOS code doesn't exist within the Windows core so you have to force the older Netbios API call.) However, it is possible to run the Java CIFS socket code, even on Windows. This is usefull as a workaround for JNI related bugs, see eg: https://issues.alfresco.com/jira/browse/ETHREEOH-2881 https://issues.alfresco.com/jira/browse/JLAN-59 https://issues.alfresco.com/jira/browse/ALF-569 https://issues.alfresco.com/jira/browse/JLAN-91 or if you want to use native SMB protocol (port 445). Indeed, the JNI CIFS code only provides the older Netbios SMB protocol (port 137, 138, 139).

The technique to use alfresco Java CIFS socket code on windows is always the same:

  • configure alfresco to use the Java CIFS socket code
  • configure the Windows server to allow alfresco to bind to the CIFS (native and netbios) ports.

The details however depend on the version of alfresco and the version of the windows server.

Alfresco configuration changes

Disable the Native Code (JNI)

For alfresco version 3.2 or after, you need to cifs.disableNativeCode=true in the alfresco-global.properties file to turn off any call to windows netbios DLLs using JNI.

Optionally, for alfresco version 3.2 can use cifs.disableNIO=true in the alfresco-global.properties file.

Modify the platforms properties

You also need to add the windows keyword to the list of platforms in the beans tcpipSMB and netBIOSSMB to the platforms property overloading the beans defined in alfresco/WEB-INF/classes/alfresco/subsystems/fileServers/default/file-servers-context.xml i.e change:

           <property name="platforms">
              <value>linux,solaris,macosx</value>
           </property>

with

           <property name="platforms">
              <value>linux,solaris,macosx,windows</value>
           </property>

Note: The <property name="platforms"> appears twice in file alfresco/WEB-INF/classes/alfresco/subsystems/fileServers/default/file-servers-context.xml, once for each protocol. It is important you change both properties to get the java socket code for netbios (port 137, 138, 139) and native cifs (port 445).

Tell Alfresco what IP to bind to

If you use the Alfresco-dedicated network interface method below, then you will also need tell alfresco to bind the native cifs service (port 445) and the netbios services (ports 137, 138, 139) to this second IP. To do this:

  • On alfresco before version 3.2: <netBIOSSMB bindto="n.n.n.n"/> and <bindto>n.n.n.n</bindto> in the file-servers-custom.xml config file.
  • On alfresco version 3.2 or after: cifs.bindto in the alfresco-global.properties file.

Windows configuration changes

Windows 2008 server

On Windows 2008 server, you basically have only one choice: deactivate windows cifs (port 445) to allow alfresco java socket code to bind to it. You can bind alfresco to port 445 using the following method:

  • Go to "Device Manager" select View and enable "show hidden devices."
  • Expand "Non-Plug and Play Drivers" and set "Message-oriented TCP/IP and TCP/IPv6 Protocol (SMB session)" to start on demand.
  • Reboot
  • Bind alfresco to port 445.
  • Start the "Message-oriented TCP/IP and TCP/IPv6 Protocol (SMB session)" driver.
  • Browse the remote shares.
Windows 2003 server

On Windows 2003 server, you can use one of the two methods:

Windows native cifs and netbios deactivation method

Switch off Windows NetBIOS and native SMB, see the [HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\NetBT\Parameters] described below

Alfresco-dedicated network interface method

This method is usually to be preferred as it allows to have the server serve windows share in parallel of serving alfresco shares. Use an alias TCP/IP address and bind the Alfresco CIFS/NetBIOS code to that address, as Windows doesn't use the alias address. To add an alias address (or virtual interface) go into the Control Panel -> Network Connections-> LAN Connections -> Properties -> Internet Protocol (TCP/IP) -> Properties -> Advanced -> IP Settings -> IP addresses -> Add, then add another IP address in there. This IP will be used to bind alfresco cifs services to. You can make sure that no windows services is running on the new nertwork interface using the command netstat -nao: nothing should be listening on ports 445, 137, 138 and 139 of the alfresco dedicated interface before you have started alfresco. This is to allow alfresco to bind to those ports. If you see something listening on this interface before you have started alfresco, then this means that you probably have to deactivate the windows cifs services on that interface (see Turning off netbios in windows 2003). If you start alfresco while a windows service is already running on that interface, you will get an error could not bind to interface, service already in use at boot time.

Make sure you also tell alfresco to bind to this new IP following Alfresco configuration changes above.

FTP Server Configuration

Configuration

The following properties can be configured for the FTP server. See Configuring Subsystems.

ftp.enabled
Enables or disables the FTP server.
ftp.port
Specifies the port that the FTP server listens for incoming connections on. Defaults to port 21. On some platforms ports below 1024 require the server to be run under a privileged account.
ftp.bindto (New as of V4.0)
Specifies the network adapter to bind to. If not specified the server will bind to all available adapters/addresses.
ftp.ipv6.enabled (Obsolete as of V3.4.2)
Enable IPv6 extensions to allow use of IPv6 style addresses. In V3.4.2 onwards, IP v6 is detected automatically and this property has no effect.
ftp.dataPortFrom
Limit the data ports to a specific range of ports, lower limit.
ftp.dataPortTo
Limit the data ports to a specific range of ports, upper limit.
ftp.keyStore
Path to the keystore file for FTPS support.
ftp.trustStore
Path to the truststore file for FTPS support.
ftp.passphrase
Passphrase for the keystore/truststore files.
ftp.requireSecureSession
If set to true then only secure FTPS sessions will be allowed to logon to the FTP server.
ftp.sslEngineDebug
Enable additional debug output from the Java SSLEngine class.

The ftp.keyStore, ftp.trustStore, and ftp.passphrase values must all be specified to enable FTPS support. Currently only explicit FTP over SSL/TLS mode is supported, and encrypted data sessions are not currently supported.

To setup the keystore and truststore files follow the instructions from the Java6 JSSE Reference Guide.

Advanced Spring Overrides

The FTP server beans are declared in the file-servers-context.xml file in WEB-INF/classes/alfresco/subsystems/fileServers/default/file-servers-context.xml. Using the subsystem extension classpath mechanism, site specific customisation of these default values can be placed in a Spring bean file in /tomcat/shared/classes/alfresco/extension/subsystems/fileServers/default/default/custom-file-servers-context.xml (note that the default/default part of the path is intentional).

The following properties are overridable on the ftpServerConfig bean

bindTo
Specifies the address the FTP server binds to, if not specified the server will bind to all available addresses.
rootDirectory
Specifies the path of the root directory as an FTP format path, ie. using forward slashes. The first part of the path should be the filesystem name optionally followed by one or more folder names, for example:
/Alfresco/myfolder/
charSet
Specifies the character set to be used. The character set name should be a valid Java character set, see the Java CharSet class for more information.

In addition, the debugFlags property enables debug output levels for FTP server debugging. The value should be a comma-separated list of flag names from the following table:

FTP server debug flags
Flag Description
State Session state changes
Search Folder searches
Info File information requests
File File open/close
FileIO File read/write
Error Errors
Pkttype Received packet type
Timing Time packet processing
Dataport Data port
Directory Directory commands
SSL FTPS specific processing


Configure logging levels for the FTP server in $ALF_HOME/tomcat/webapps/alfresco/WEB-INF/classes/log4j.properties using:

log4j.logger.org.alfresco.ftp.protocol=debug
log4j.logger.org.alfresco.ftp.server=debug

NFS Server Configuration

It is recommended that TCP connections are used to connect to the Alfresco NFS server. Using a read/write size of 32K will also help to optimize the performance.

Configuration

The following properties can be configured for the NFS server. See Configuring Subsystems.

nfs.enabled
Enables or disables the NFS server
nfs.nfsServerPort
The port number to run main NFS server service on. The default is to allocate the default NFS port: 2049. This may clash with a running native NFS server.
nfs.mountServerPort
The port number to run the mountserver service on. The default is to allocate an available non-privileged port.
nfs.portMapperPort
The port number to run the portmapper service on. The default port is 111. To prevent the NFS server and mount server registering with a portmapper set nfs.portMapperPort to -1
nfs.rpcRegisterPort
RPC registration port, 0 will allocate next available port.
nfs.portMapperEnabled
Enables the built-in portmapper service. This would usually be enabled on Windows where there isn't a default portmapper service. Under Linux/Unix operating systems the built-in portmapper service can be used, this also saves having to run the Alfresco server using the root account.
nfs.user.mappings
A composite property that configures the user id/group id to Alfresco user name mappings that are used by the current RPC authentication implementation.

For example, the following configuration gives admin a uid and gid of 0 and auser a uid and gid of 501.

nfs.user.mappings=admin,auser
nfs.user.mappings.value.admin.uid=0
nfs.user.mappings.value.admin.gid=0
nfs.user.mappings.value.auser.uid=501
nfs.user.mappings.value.auser.gid=501

Advanced Spring Overrides

The NFS server beans are declared in the file-servers-context.xml file in WEB-INF/classes/alfresco/subsystems/fileServers/default/file-servers-context.xml. Using the subsystem extension classpath mechanism, site specific customisation of these default values can be placed in a Spring bean file in /tomcat/shared/classes/alfresco/extension/subsystems/fileServers/default/default/custom-file-servers-context.xml (note that the default/default part of the path is intentional).

The following properties are overridable on the nfsServerConfig bean

portMapperEnabled
Enables the built-in portmapper service. This would usually be enabled on Windows where there isn't a default portmapper service. Under Linux/Unix operating systems the built-in portmapper service can be used, this also saves having to run the Alfresco server using the root account.
threadPool
Sets the size of the RPc processing thread pool. The minimum number of threads is 4, the default setting is 8.
packetPool
Sets the size of the packet pool used to receive RPC requests and send RPC replies. The minimum number of packets is 10, the default setting is 50.
portMapperPort
The port number to run the portmapper service on. The default port is 111.
mountServerPort
The port number to run the mountserver service on. The default is to allocate an available non-privileged port.
nfsServerPort
The port number to run main NFS server service on. The default is to allocate the default NFS port: 2049. This will likely clash with a running native NFS server.

In addition, the debugFlags property enables debug output levels for NFS server debugging. The value should be in the form of a comma-separated list of the flag names in the table below.

NFS server debug flags
Flag Description
RxData Request data details
TxData Response data details
DumpData Hex dump request/response data
Search Folder searches
Info File information requests
File File open/close
FileIO File read/write
Error Error responses
Directory Directory requests (readdir/readdirplus)
Timing Request timing
Session Session creation/deletion

The log4j.properties file must also have NFS protocol debug output enabled using:

log4j.logger.org.alfresco.nfs.server=debug

The following logging level must also be enabled to log debug output from the core file server code:

log4j.logger.org.alfresco.fileserver=debug

There are also the following log4j output options for the NFS/mount/portmapper services:

log4j.logger.org.alfresco.nfs.protocol=debug

Output server level debug information from the NFS, mount and portmapper services.

log4j.logger.org.alfresco.nfs.protocol.auth=debug

Output RPC authentication debugging.

NFS Gotchas

  • NFS server port number is not ephemeral. Contrary to what has been documented until recently, if the NFSServerPort property is not given it defaults to 2049. This will likely conflict with the a native NFS server, if any. The portmapper daemon when properly used removes any dependency upon a well known port number, however neither Alfresco nor any native NFS server seem to employ this functionality.
  • Running native & Alfresco NFS servers on the same host. If you wish to run the native along side Alfresco's NFS server you cannot depend upon the portmapper, as there is a 50% chance that it will retain the native NFS details . When using nfs-utils-1.0.10 version on Linux, mount.nfs will defer to the portmapper for the port-number, version-number and protocol of the NFS server in question. Only if all three of these are supplied on the command line will the mount command directly contact the Alfresco NFS server. Failing this, mount.nfs will fail, as it cannot find the server you have described in the portmapper table. You must therefore configure both MountServerPort and NFSServerPort to known values above 1024. Afterward the following command line should succeed...
mount -onolock,port=yourNfsPort,mountport=yourMountPort,proto=tcp yourFfsServerName:/alfresco /mnt/alfresco/

NB: the proto option may be either tcp or udp. In retrospect it appears desirable to have functionality to resolve the NFS server required by the volume requested. As it stands this doesn't happen, and the portmapper only searches for the NFS server on the version and protocol.

NFS client configuration

Alfresco NFS does not implement NFS locks.

That means that you should mount alfresco NFS using a no lock option.

On Linux this means using -o nolock, for instance:

 mount -vvvvv -t nfs -o nolock localhost:/alfresco /mnt/

On (Open)Solaris this means using -o llock (local locking):

 mount -F nfs -o llock 10.69.69.1:/alfresco /mnt/

Filesystem Access Control Configuration

It is possible to control access to all JLAN mounted filesystems [CIFS, FTP and NFS only] though global access controls. A filesystem access control defines the level of access that should apply to requests that fall within a certain scope. Access controls may be defined for multiple scopes, meaning that different user subsets can have different levels of access.

The filesystem access control configuration is a similar concept to the *nix command mount which may specify ro for read-only and rw for read-write access.

Filesystem access controls operate in addition to any repository level access control. So, for example, even if the ftp filesystem is configured to be read/write, the user may still be denied read or write access to a particular file by the repository.

The levels and scopes that may be defined for a filesystem access control are explained in the following subsections.

Access Control Levels

None
The filesystems are not accessible or even visible to requests in scope of the access control
Read
The filesystems are readable but not writable to requests in scope of the access control
Write
The filesystems are readable and writable to requests in scope of the access control

Access Control Scopes

Access controls may be defined with the following scopes:

Default
applies to all requests to which no other access control applies
Domain
applies to all requests from users in a particular domain
Protocol
applies to all requests made through a protocol in a given list of protocols. Protocols can include SMB, CIFS, NFS, and FTP.
User
applies to all requests from a particular user

Configuration

Filesystem access controls provide another level of access control above that provided by the alfresco repository. So for example you could configure that all ftp access is read only even though usually the configured user would have read/write access to the content.

This is an additional layer of security so for example if the repository is read only then nothing in the filesystem configuration will be able to over-ride that to read/write access. Or if a node cannot be read by the current user then nothing in the filesystem configuration will be able to grant read access.

The filesystem access controls are configured by composite properties which are added to either alfresco-global.properties or on Alfresco Enterprise via the JMX console.

Filesystem access controls can be defined using the following composite properties:

Global Access Level

filesystem.acl.global.defaultAccessLevel
Defines the default access level. Directly names the access control level (None, Read or Write) that applies to requests that are not in scope of any other access control. Note that it is not valid to use the value None without defining other access controls.

Domain Access Level

filesystem.acl.global.domainAccessControls
Defines the set of access controls with domain scope. This is a composite property whose value should be a comma-separated list of domain names. To define the access level for one of the listed domains, use the property filesystem.acl.global.domainAccessControls.value.Domain.accessType.

The example below defines Read level access for DOMAIN1 and Write level access for DOMAIN2.

filesystem.acl.global.domainAccessControls=DOMAIN1,DOMAIN2
filesystem.acl.global.domainAccessControls.value.DOMAIN1.accessType=Read
filesystem.acl.global.domainAccessControls.value.DOMAIN2.accessType=Write

Protocol Access Controls

filesystem.acl.global.protocolAccessControls
Defines the set of access controls with protocol scope. This is a composite property whose value should be a comma-separated list of access control names. To define the access level for a named access control and the set of protocols to which it applies, use the properties:
  • filesystem.acl.global.protocolAccessControls.value.Name.accessType
  • filesystem.acl.global.protocolAccessControls.value.Name.checkList
Protocols can include SMB, CIFS, NFS, and FTP.

The example below defines Read level access for NFS and Write level access for CIFS and FTP.

filesystem.acl.global.protocolAccessControls=nfs,cifs,ftp
filesystem.acl.global.protocolAccessControls.value.nfs.accessType=Read
filesystem.acl.global.protocolAccessControls.value.nfs.checkList=NFS
filesystem.acl.global.protocolAccessControls.value.others.accessType=Write
filesystem.acl.global.protocolAccessControls.value.others.checkList=CIFS
filesystem.acl.global.protocolAccessControls.value.others.accessType=Write
filesystem.acl.global.protocolAccessControls.value.others.checkList=FTP

User Access Controls

filesystem.acl.global.userAccessControls
Defines the set of access controls with user scope. This is a composite property whose value should be a comma-separated list of user names. To define the access level for one of the listed users, use the property filesystem.acl.global.userAccessControls.value.User.accessType.

The example below defines Read level access for user1 and Write level access for user2.

filesystem.acl.global.userAccessControls=user1,user2
filesystem.acl.global.userAccessControls.value.user1.accessType=Read
filesystem.acl.global.userAccessControls.value.user2.accessType=Write

Advanced Server Configuration

Most common configuration of the file server subsystem can be done though adding properties to alfresco-global.properties however the filesystem is also configurable through spring for extension and customisation.

The fileystem server settings are configured via the file-servers-context.xml file in WEB-INF/classes/alfresco/subsystems/fileServers/default/file-servers-context.xml. Using the subsystem extension classpath mechanism, specific customisation of the default settings can be placed in a Spring bean file in /tomcat/shared/classes/alfresco/extension/subsystems/fileServers/default/default/custom-file-servers-context.xml (note that the default/default part of the path is intentional).

Custom Filesystem Configuration

The default configuration creates filesystems for the spaces store and all AVM stores with access to all versions of stores. You can customize this filesystem configuration by overriding the filesystemContexts list bean, which declares the list of filesystems mounted by the file servers.

There are two types of bean that included in this list, representing the two types of store implemented by alfresco: the alfresco store filesystem and the AVM store. The repository shared filesystems are configured using the org.alfresco.filesys.repo.ContentContext class, and the AVM filesystems are configured using the org.alfresco.filesys.avm.AVMContext class.

To share all available AVM stores as seperate shares, set the avmAllStores property of the fileServerConfiguration bean to true. This will create a shared filesystem for each available AVM store using the same name as the store. The shared filesystems are writeable as they share the head version of the stores.

Alfresco Filesystems

The class org.alfresco.filesys.repo.ContentContext declares a repository filesystem.

Repository filesystems require a storeName and rootPath. The default configuration creates an Alfresco filesystem using the name and root path of the spaces store.

The optional relativePath property can be specified to set the root of the filesystem at a particular folder. The relative path can be specified using forward or back slashes, and may contain multiple levels.

The repository filesystem supports the adding of two types of 'pseudo file' into the folders of the filesystem.

URL files
open the browser at the web location of the folder. The URLFileName property controls the name given to these pseudo files, and the URLPrefix property sets the absolute root of the generated URLs
Desktop Actions
are special executables that can be run on the client side to trigger actions on files and folders. These are specified using the globalDesktopActionConfig and desktopActionList properties. For more details, see Desktop Actions.

The disableNodeMonitor property is used to disable the monitoring of node service events for this filesystem. Node service monitoring is used to generate CIFS change notifications and update the file state cache when nodes are added, deleted, updated outside of the file server, this includes rule processing where files may be moved or new files generated.

AVM Filesystems

Warning: AVM Deprecation
The AVM is no longer being actively developed by Alfresco Engineering and Enterprise support subscriptions for the AVM are no longer being offered to new customers. New projects requiring Web Content Management features may want to consider leveraging a CMIS-based solution such as Web Quick Start or the File System Transfer Receiver. The topic AVM Decommissioning collects useful information for migrating off of the AVM.

The class org.alfresco.filesys.avm.AVMContext declares an AVM filesystem.

The filesystem may be mapped to an individual store within AVM or it can be a view onto all available stores using a pseudo folders at the top of the hierarchy to provide access to all versions of the stores.

To create an AVM filesystem mapped to a particular store use the following:

           <bean class="org.alfresco.filesys.avm.AVMContext">
              <property name="deviceName">
                 <value>STORE</value>
              </property>
              <property name="storePath">
                 <value>main:/</value>
              </property>
              <property name="version">
                 <value>-1/value>
              </property>
              <property name="createStore">
                 <value>true</value>
              </property>
           </bean>

The storePath property contains the store name and optionally a relative path. The version property contains the version of the store to be shared, this defaults to -1 which is allows writing to the store. If the version property is not -1 the filesystem will be read-only.

The createStore property can be set to true to create a new store when the server is started. The new store will only be created if it does not already exist.

To share all AVM stores with access to all versions of stores the virtualization view can be used, this is configured using the following:

           <bean class="org.alfresco.filesys.avm.AVMContext">
              <property name="deviceName">
                 <value>AVM</value>
              </property>
              <property name="virtualView">
                 <value>true</value>
              </property>
              <property name="stores">
                 <value>normal,site,staging,author,preview</value>
              </property>
           </bean>


By default the virtualization view filters out workflow preview and author preview sandboxes/stores, and only shows the web project store and author store for the logged in user. If the user is a content manager on one or more web projects then all author sandboxes will be shown. For the admin user all sandboxes are shown.

The optional stores property can be used to specify the types of stores/sandboxes that are visible in the virtualization view, as a comma delimited list. The default view will show staging and author sandboxes/stores, with the access control filtering applied to the view on a per user basis.

The available store/sandbox types to show are:

normal
Show normal stores, that are not part of a web project.
site
Show site data stores.
staging
Show web project staging sandboxes. the web project sandbox will be read-only to normal users.
author
Show author sandboxes. The sandbox will be writable.
preview

Show staging preview and author preview sandboxes.

You can create multiple AVM/WCM views by adding multiple filesystem definitions to the filesystemContexts list. Each filesystem definition must have a unique name.

The virtualization view shows all stores and versions using the following layout:

[store name]
  \HEAD
    \DATA
      \[folder]
      ..
    \METADATA
  \VERSION
    \vn
      \DATA
        \[folder]
        ..
      \METADATA
    ..
    \v-1
      \DATA
        \[folder]
        ..
      \METADATA
[store name]
..

Share Mappers

You can set the shareMapper property of the fileSecurityConfig bean to an instance of one of the classes described below in order to control the dynamic generation of extra filesystems, in addition to any of those listed in filesystemContexts.

Home Folder Filesystem

The org.alfresco.filesys.alfresco.HomeShareMapper class creates a dynamic repository filesystem that maps to the logged on users home space.

The homeShareName property specifies the name of the filesystem. The default home folder filesystem name is HOME.

Using SMB/CIFS this will be the name of the share. Using FTP this will be a folder in the root area.

AVM Share Version Mapper

Warning: AVM Deprecation
The AVM is no longer being actively developed by Alfresco Engineering and Enterprise support subscriptions for the AVM are no longer being offered to new customers. New projects requiring Web Content Management features may want to consider leveraging a CMIS-based solution such as Web Quick Start or the File System Transfer Receiver. The topic AVM Decommissioning collects useful information for migrating off of the AVM.

The org.alfresco.filesys.avm.AVMShareMapper class enables access to any version of any store using a special format of share name. When mapping a drive/mounting a CIFS share, the share name is specified using the format <storeName>_<versionId> This creates a dynamic share that is mapped to the specified store/version that is only visible to CIFS connecting session.

The AVM share mapper cannot be used at the same time as the org.alfresco.filesys.alfresco.HomeShareMapper.

Desktop Actions

Desktop actions allow a client-side application on the Alfresco CIFS server to trigger a server-side action. The action is run in the context of the folder the application is running in. Files and/or folders may be dragged onto the client-side application, these are then passed as parameters to the server-side action.

The desktop action applications are added to a folder using pseudo files. The same application executable appears as different files that are then mapped to different actions on the server.

In order to run a desktop action you must have connected to an Alfresco CIFS server, this creates an authenticated session to the server. The desktop action is called by passing the request over the CIFS session so it is executed as the connected user.

Pre Processing

The clients-side application performs various pre-processing tasks for the action. The action indicates whether it accepts files and/or folders to be dragged onto the application. The files/folders may be in the same folder as the application, in a seperate folder on the Alfresco network drive or on a drive that is local to the client. The action indicates which combinations of files/folders are acceptable via a set of attributes.

If the action accepts files/folders that are on a drive local to the client then the files/folders will be copied to the Alfresco folder in order to be accessible to the server-side action. There is an option to only allow copying of files that match a working copy in the destination folder.

Files/folders are copied to the Alfresco folder using the Windows shell, larger transfers will display the standard progress dialog and file overwrites will display a dialog allowing the user to continue or cancel.

The client-side application can display a message to confirm if the action should be run or not.

File/Folder Parameters

Once the client-side pre-processing is completed any target files/folders that were dropped onto the application will now be on the Alfresco file server. A list of the files/folders is passed to the server-side action indicating if the file is a copy or already existed on the Alfresco server. Before calling the server-side action code the file/folder paths are converted to their NodeRef.

Server-side Action

The server-side action runs in the context of the authenticated CIFS user. The action returns a status and optional message to the client.

The action response can return a URL for the client-side application to launch a web browser, or a commandline for the client-side application to run.

Configuration

Desktop actions are configured on a per filesystem basis by overriding the filesystem definition in file-servers-context.xml. The default file-servers-context.xml file contains a commented out section with a sample desktop actions configuration.

The following configuration enables the sample desktop actions (Echo, URL, CmdLine, CheckInOut, Javascript):

            <!-- Alfresco repository access shared filesystem -->
            <bean class="org.alfresco.filesys.repo.ContentContext">
               <property name="deviceName">
                  <value>${filesystem.name}</value>
               </property>
               <property name="storeName">
                  <value>${spaces.store}</value>
               </property>
               <property name="rootPath">
                  <value>/${spaces.company_home.childname}</value>
               </property>
               <!-- Add a URL file to each folder that links back to the web client -->
               <property name="URLFileName">
                  <value>__Alfresco.url</value>
               </property>
               <property name="URLPrefix">
                  <value>${cifs.urlfile.prefix}</value>
               </property>
               <!-- Mark locked files as offline -->
               <property name="offlineFiles">
                  <value>true</value>
               </property>

               <!-- Desktop actions -->
               <!-- Uses a client-side application to trigger a server-side action                         -->
               <!--   Echo - displays a message echoed from the server                                     -->
               <!--   URL  - launches a URL via the Windows shell                                          -->
               <!--   CmdLine - launches the Notepad application                                           -->
               <!--   CheckInOut - checks files in/out, drag and drop files onto the application           -->
               <!--   JavaScript - run a server-side script                                                -->
               <!--   JavaScriptURL - server-side script that generates a URL to the folder using a ticket -->
               <!--                   to avoid having to logon                                             -->
               <property name="globalDesktopActionConfig">
                  <bean class="org.alfresco.filesys.config.GlobalDesktopActionConfigBean">
                     <property name="path">
                        <value>alfresco/desktop/Alfresco.exe</value>
                     </property>
                     <property name="webpath">
                        <value>${cifs.urlfile.prefix}</value>
                     </property>
                  </bean>
               </property>
               <property name="desktopActionList">
                  <list>
                     <bean class="org.alfresco.filesys.repo.desk.EchoDesktopAction">
                        <property name="name">
                           <value>Echo</value>
                        </property>
                        <property name="filename">
                           <value>__AlfrescoEcho.exe</value>
                        </property>
                     </bean>
                     <bean class="org.alfresco.filesys.repo.desk.URLDesktopAction">
                        <property name="name">
                           <value>URL</value>
                        </property>
                        <property name="filename">
                           <value>__AlfrescoURL.exe</value>
                        </property>
                     </bean>
                     <bean class="org.alfresco.filesys.repo.desk.CmdLineDesktopAction">
                        <property name="name">
                           <value>CmdLine</value>
                        </property>
                        <property name="filename">
                           <value>__AlfrescoCmd.exe</value>
                        </property>
                     </bean>
                     <bean class="org.alfresco.filesys.repo.desk.CheckInOutDesktopAction">
                        <property name="name">
                           <value>CheckInOut</value>
                        </property>
                        <property name="filename">
                           <value>__CheckInOut.exe</value>
                        </property>
                     </bean>
                     <bean class="org.alfresco.filesys.repo.desk.JavaScriptDesktopAction">
                        <property name="name">
                           <value>JavaScript</value>
                        </property>
                        <property name="filename">
                           <value>__AlfrescoScript.exe</value>
                        </property>
                        <property name="scriptName">
                           <value>alfresco/desktop/dumpRequest.js</value>
                        </property>
                        <property name="attributeList">
                           <value>anyFiles, multiplePaths, allowNoParams</value>
                        </property>
                        <property name="preprocess">
                           <value>confirm, copyToTarget</value>
                        </property>
                     </bean>
                  </list>
               </property>
            </bean>

The globalDesktopActionConfig property holds a org.alfresco.filesys.config.GlobalDesktopActionConfigBean containing settings and overrides that apply to all the defined actions. The path property specifies the location of the executable that is used by the action pseduo files. The file should be on the classpath. The default path value is alfresco/desktop/Alfresco.exe. The webpath property specifies the URL of the Alfresco web application. The ${localname} token in the web application URL is replaced with the local host DNS name or TCP/IP address. To switch off action confirmations the noConfirm propery can be set to switch off confirmations for all actions. This overrides the preprocess property of all org.alfresco.filesys.repo.desk.JavaScriptDesktopAction desktop actions as if confirm was removed from the preprocessing action list in their preprocess properties. See Writing A Javascript Desktop Action.

The desktopActionList property lists the individual desktop actions. These must be of a class that extends the org.alfresco.filesys.smb.server.repo.DesktopAction class. The available classes are demonstrated in the configuration above.

All action classes have name, filename and debug properties. The name property specifies the action name. The filename property specifies the name of the file that will appear in the folder listing. The debug property will enable debug output for the action.

Writing A Java Desktop Action

A desktop action only requires the server-side code to be implemented, the same client-side application is used for all actions. The client-side application uses information from the server-side action to determine how to validate parameters, display confirmations, launch the web browser etc.

A desktop action must be derived from the org.alfresco.filesys.alfresco.DesktopAction abstract class.

Action Attributes

The attributes property is a combination of bit flags that specify:

  • the types of parameters that the action accepts
  • whether or not the parameters are optional
  • the way in which parameters should be passed to the action.

Any of the following values can be combined (with a bitwise OR operation '|').

Java Constant Description
AttrTargetFolders Accepts sub-folders from the same folder as the application
AttrClientFiles Accepts files from a client local drive. Files will be copied to the target folder on the Alfresco filesystem.
AttrClientFolders Accepts folders from a client local drive. Folders will be copied to the target folder on the Alfresco filesystem.
AttrAlfrescoFiles Accepts files from another folder on the same Alfresco filesystem
AttrAlfrescoFolders Accepts folders from another folder on the same Alfresco filesystem
AttrMultiplePaths Indicates that the action accepts all parameter paths in one call to the server-side action. If not set the action will be called multiple times with one path per call.
AttrAllowNoParams Indicates that file/folder parameters are optional. Used in combination with the AttrTarget/AttrClient/AttrAlfresco attributes.

The following convenience values can be used to specify the file/folder types that the action accepts. They are combinations of the above flags.

Java Constant Attribute Combination
AttrAnyFiles AttrTargetFiles AttrClientFiles AttrAlfrescoFiles
AttrAnyFolders AttrTargetFolders AttrClientFolders AttrAlfrescoFolders
AttrAnyFilesFolders AttrAnyFiles AttrAnyFolders
Pre-processing Actions

The preProcessActions property is a combination of bit flags that specify processing that the client-side application performs before calling the server-side action.

Any of the following values can be combined (with a bitwise OR operation '|').

Java Constant Description
PreCopyToTarget Copy files/folders from another Alfresco folder to the target folder
PreConfirmAction Display a dialog box allowing the user to abort the action. The confirmation message is supplied by the server-side action.
PreLocalToWorkingCopy Files copied from a local drive must have a matching file in the target folder that is a working copy.
Action Class Methods

When the ServerConfigurationBean is initialized by the Spring container on startup, the initializeAction(AlfrescoDiskDriver, AlfrescoContext) method of each file context's actions is called. The default implementation completes initialization of an action by associating it with a driver and context and validating properties have valid values. If you need to do further initialization, such as setting action attributes and preprocessing actions, you can override this method to do so.

The main action method that must be implemented is the runAction(DesktopParams) method. The DesktopParams class contains the details of the parameters passed from the client-side application plus details of the target folder node and folder file.

The details of each file/folder parameter is contained within a DesktopTarget object. The DesktopParams class holds a list of DesktopTarget objects. If the AttrMultiplePaths attribute was not specified the parameter list will only contain one value.

Each DesktopTarget object contains the path to the file/folder, the NodeRef of the file/folder and a type value. the type value indicates if the file/folder was copied during the client-side pre-processing.

The runAction() method should return a DesktopResponse object, this contains the status and optional status message. The following status codes may be returned:

Status Code Description
StsSuccess Action completed normally. Optional message will cause an information dialog to be displayed on the client.
StsError Action error. Error message will be displayed in a dialog on the client.
StsFileNotFound File not found error. Optional message can give more details of the problem path.
StsAccessDenied Access denied.
StsBadParameter Bad parameter.
StsNotWorkingCopy File is not a working copy.
StsNoSuchAction Action not found.
StsLaunchURL Launch a web browser using the URL specified in the status message.
StsCommandLine Launch an application using the command line specified in the status message.

If the PreConfirmAction pre-processing action has been enabled for the action then the String getConfirmationString() method should be used to provide the message displayed in the confirmation dialog. If no string is provided the default message of 'Run Action ?' is used. The dialog diaplayed has Ok and Cancel buttons.

If the desktop action returns the StsLaunchURL status the URL can be built using the DesktopParams.getWebPath() method to get the base URL of the Alfresco web application. To bypass the user having to login when the web browser is launched on the client an authentication ticket can be appended to the URL in the format ?ticket=<authticket>. The authentication ticket string for the user can be retrieved from the DesktopParams object using the getTicket() method.

The command line may contain environment variable tokens that are expanded by the client-side application. The tokens are in the format %<env-var-name>%, eg. %SystemRoot%\Notepad.exe would launch the Notepad application from the Windows system folder.

A special token of %AlfrescoDir% is expanded to the working directory that the client-side application is running from.

Sample Desktop Action

The following code is a very simple desktop action that echoes a message with the current date/time, the message is then displayed by the client-side application.

/**
 * Echo Desktop Action Class
 * 
 * Simple desktop action that echoes back a test message with the current date/time.
 * 
 * @author gkspencer
 */
public class EchoDesktopAction extends DesktopAction {

  /**
   * Class constructor
   *
   * Action does not take any parameters (attributes = 0) and requires confirmation
   * before running.
   */
   public EchoDesktopAction()
   {
     super( 0, PreConfirmAction);
   }
	
   /**
    * Return the confirmation string displayed by the client
    *
    * @return String
    */
   public String getConfirmationString() {
     return "Run echo action";
   }

   /**
    * Run the action, return a message to be displayed by the client application
    *
    * @param params DesktopParams
    * @return DesktopResponse
    */
   public DesktopResponse runAction(DesktopParams params) {
     // Return a text message
     return new DesktopResponse(StsSuccess, "Test message from echo action at "   new Date()); 
   }
 }

Writing A Javascript Desktop Action

The JavaScriptDesktopActionallows a desktop action to be scripted without needing to compile, and install, a Java class. The JavaScript desktop actions have the same capabilities as the Java based actions.

For a JavaScript desktop action the attributes and pre-processing flags are specified as strings via special properties, along with the path to the script file. The script file must exist on the classpath, this should be a normal file on the local filesystem as the JavaScript desktop action will open the script file as a file stream, i.e. the script cannot be stored in a Jar file. The JavaScript action will also check if the script file has been updated and automatically reload the updated script.

To configure a JavaScript desktop action the following bean is added to the list of beans configured for as the desktopActionList property of a filesystem context.

                    <bean class="org.alfresco.filesys.repo.desk.JavaScriptDesktopAction">
                       <property name="name">
                          <value>JavaScript</value>
                       </property>
                       <property name="filename">
                          <value>__AlfrescoScript.exe</value>
                       </property>
                       <property name="scriptName">
                          <value>alfresco/desktop/dumpRequest.js</value>
                       </property>
                       <property name="attributeList">
                          <value>anyFiles, multiplePaths, allowNoParams</value>
                       </property>
                       <property name="preprocess">
                          <value>confirm, copyToTarget</value>
                       </property>
                    </bean>

In this example the script file, dumpRequest.js, will be located in the WEB-INF/classes/alfresco/desktop folder.

The attributeList property may contain a combination of the following flags, as a comma separated list:

Flag Description
targetFiles Accepts files from the same folder as the application
targetFolders Accepts sub-folders from the same folder as the application
clientFiles Accepts files from a client local drive. Files will be copied to the target folder on the Alfresco filesystem.
clientFolders Accepts folders from a client local drive. Folders will be copied to the target folder on the Alfresco filesystem.
alfrescoFiles Accepts files from another folder on the same Alfresco filesystem
alfrescoFolders Accepts folders from another folder on the same Alfresco filesystem
multiplePaths Indicates that the action accepts all parameter paths in one call to the server-side action. If not set the action will be called multiple times with one path per call.
allowNoParams Indicates that file/folder parameters are optional. Used in combination with the target/client/alfresco attributes.
anyFiles targetFiles clientFiles alfrescoFiles
anyFolders targetFolders clientFolders alfrescoFolders
anyFilesFolders anyFiles anyFolders


The preprocess propery may contain a combination of the following flags, as a comma separated list:

Flag Description
copyToTarget Copy files/folders from another Alfresco folder to the target folder
confirmAction Display a dialog box allowing the user to abort the action. The confirmation message is supplied by the server-side action.
localToWorkingCopy Files copied from a local drive must have a matching file in the target folder that is a working copy.

The script is called by the JavaScriptDesktopAction with the target parameters from the client available as script objects. The following objects are available:

JavaScript Object Description
deskParams The desktop action parameters
webURL URL of the Alfresco web application, in the format http://server:port/webapp/
actions Allows access to the public services
logger Script debug logging
Desktop Parameters

The deskParams object contains the details of the folder the action is running from and the target files/folders for the action. The target list may be empty if the action has the allowNoParams attribute. The list will only contain a single target if the multiplePaths attribute is not set, although the client-side application will accept multiple paths it will call the action with a single target at a time.

The following methods are available on the deskParams object:

Method Description
getFolderNode() Returns the NodeRef of the folder the action is running from
getFolder() Returns the NetworkFile of the folder. Use getFullName() to return the share relative path of the folder.
numberOfTargetNodes() Return the count of desktop targets for this request
getTarget(int) Return the specified desktop target object
getTicket() Return the authentication ticket string that can be used in URLs by appending ?ticket=<authticket>

The desktop target object returned by the deskParams.getTarget(n) method has the following methods:

Method Description
getType() Returns the target type
getTypeAsString() Returns the target type as a string. The value is 'File', 'Folder', 'File Copy', 'Folder Copy' or 'NodeRef'
getTarget() Returns the share relative path to the target file/folder
getNode() Return the NodeRef of the target file/folder
Desktop Response

The script may return a status string if an error occurs or one of the special status codes is being used, such as to pass a URL to the client or a commandline. A null return indicates that the script was successful.

The following status strings are available. They are encoded in the format <status-code>,<message text>.

Status String Description
0,message Success status with an informational message for the client to display
1,error General error status
2,message File not found status
3,message Access denied status
4,message Bad parameter status
5,message Not a working copy status
6,message No such action status
7,URL Launch a URL on the client via the Windows shell
8,cmdline Launch an application on the client using the specified command line

Pool Configuration

In version 3.0 of the Alfresco JLAN Server code the CIFS server component was changed to use a thread pool and memory pool along with NIO socket based code. A new coreServerConfigBean propery has been added to the fileServerConfiguration bean to allow the thread pool and memory pool to be tuned. This optional property holds an instance of type org.alfresco.filesys.config.CoreServerConfigBean whose properties are described below.

Thread Pool Configuration

The thread pool settings allow the initial and maximum number of threads to be specified, via the threadPoolInit and threadPoolMax properties. The default thread pool size is 25 initial threads with a maximum of 50 threads. This setting should be sufficient to handle up to 500 concurrent connections, depending on how active the connections are. The maximum number of threads that can be configured to the thread pool is 250 threads.

There is also thread pool debugging output available via the threadPoolDebug property.

Memory Pool Configuration

The memoryPacketSizes property allows control over the size, initial allocation and maximum allocation of the packets in the memory pool. It contains a list of org.alfresco.filesys.config.MemoryPacketConfigBean beans, each of which posses the following properties

size
A packet size, specified in bytes or Kilobytes by using the nK format.
init
The initial number of packets of this size.
max
The maximum number of packets of this size. This should be at least equal to the maximum number of threads in the thread pool. The processing of a CIFS request can use two packets per request, in the case where the request is shorter than the response, such as a file read or folder search.

Unless you fully understand the implications of changing the memory pool parameters it is advised to use the default settings. Incorrect setup of the memory pool will impact the performance of the CIFS server and can cause errors.

Example

  <bean id="fileServerConfiguration" class="org.alfresco.filesys.config.ServerConfigurationBean" parent="fileServerConfigurationBase">
     <property name="cifsConfigBean">
        <ref bean="cifsServerConfig" />
     </property>
     <property name="ftpConfigBean">
        <ref bean="ftpServerConfig" />
     </property>
     <property name="nfsConfigBean">
        <ref bean="nfsServerConfig" />
     </property>
     <property name="filesystemContexts">
        <ref bean="filesystemContexts" />
     </property>
     <property name="securityConfigBean">
        <ref bean="fileSecurityConfig" />
     </property>
     <property name="coreServerConfigBean">
        <bean class="org.alfresco.filesys.config.CoreServerConfigBean">
           <property name="threadPoolInit">
              <value>25</value>
           </property>
           <property name="threadPoolMax">
              <value>50</value>
           </property>
           <property name="threadPoolDebug">
              <value>false</value>
           </property>
           <property name="memoryPacketSizes">
              <list>
                 <bean class="org.alfresco.filesys.config.MemoryPacketConfigBean">
                    <property name="size">
                       <value>256</value>
                    </property>
                    <property name="init">
                       <value>20</value>
                    </property>
                    <property name="max">
                       <value>100</value>
                    </property>
                 </bean>
                 <bean class="org.alfresco.filesys.config.MemoryPacketConfigBean">
                    <property name="size">
                       <value>4K</value>
                    </property>
                    <property name="init">
                       <value>20</value>
                    </property>
                    <property name="max">
                       <value>50</value>
                    </property>
                 </bean>
                 <bean class="org.alfresco.filesys.config.MemoryPacketConfigBean">
                    <property name="size">
                       <value>16K</value>
                    </property>
                    <property name="init">
                       <value>5</value>
                    </property>
                    <property name="max">
                       <value>50</value>
                    </property>
                 </bean>
                 <bean class="org.alfresco.filesys.config.MemoryPacketConfigBean">
                    <property name="size">
                       <value>64K</value>
                    </property>
                    <property name="init">
                       <value>5</value>
                    </property>
                    <property name="max">
                       <value>50</value>
                    </property>
                 </bean>
              </list>
           </property>
        </bean>
     </property>
  </bean>

Troubleshooting

Password Error

Sometimes, when connecting to an Alfresco share, the login dialog appears several times until finally taking effect. This problem can be caused by the client connecting to the Windows file server that is running on native SMB/port 445 rather than trying to connect via NetBIOS.

Turning off windows native SMB (port 445)

Native SMB can be disabled by adding the following registry key:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\NetBT\Parameters]
"SMBDeviceEnabled"=dword:00000000

A reboot is required after creating this key. Setting the value to one or deleting the registry key will restore native SMB support.

In Windows 2000,2003,2008 - Port 445 is bound by default to \device\ - all devices. Use the following registry key to unbind port 445 and allow for binding by Alfresco: [HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\NetBT\Parameters]

WARNING: Changing this setting may leave you unable to login to your server using Remote Desktop.

  1. In the right-hand side of the window find an option called "TransportBindName".
  2. Double click that value, and then delete the default value, thus giving it a blank value.
  3. Close the registry editor.
  4. Reboot your computer.

After rebooting open a command prompt and in it type "netstat -an"

See that it no longer listens to port 445.

Turning off windows native SMB (port 445) on Vista And Windows 2008

The SMBDeviceEnabled registry key does not seem to be recognized on Vista and Windows 2008. In order to stop native SMB being used when the Alfresco CIFS server is being run under Vista or Windows 2008 the firewall rules can be updated to block inbound connections on port 445.

To setup the Windows firewall on the system running the Alfresco CIFS server:

  1. Run the Windows Firewall with Advanced Security application. On Vista go to Control Panels, Administrative Tools. on Windows 2008 go to Start, Administrative Tools.
  2. Click on the Inbound Rules item in the left hand column.
  3. Scroll down to the File and Printer Sharing rules.
    The following rules should be enabled and set to Allow - File And Printer Sharing (NB-Datagram-In), File And Printer Sharing (NB-Name-In) and File And Printer Sharing (NB-Session-In).
    The File And Printer Sharing (SMB-In) rule should be enabled and set to Block. This blocks the native SMB/port 445 traffic.
    The other File And Printer Sharing (...) rules are not required and can be left as is.

Turning off windows SMB2 on Vista And Windows 2008

In some cases you may need to disable smb 2.0 on windows 2008

  1. Run "regedit" on Windows Server 2008 based computer.
  2. Expand and locate the sub tree as follows.
    HKLM\System\CurrentControlSet\Services\LanmanServer\Parameters
  3. Add a new REG_DWORD key with the name of "Smb2" (without quotation mark)
    • Value name: Smb2
    • Value type: REG_DWORD
  4. Set the value to 0 to disable SMB 2.0, or set it to 1 to re-enable SMB 2.0.
  5. Reboot the server.

Turning off netbios in windows 2003

When you use the java socket code on windows 2003 and have two network interfaces, you can tell windows to stop running the netbios servers (netstat -nao shows:

TCP    160.55.51.228:139      0.0.0.0:0              LISTENING       4
UDP    160.55.51.228:137      *:*                                    4
UDP    160.55.51.228:138      *:*                                    4

using the method described at: http://www.petri.co.il/disable_netbios_in_w2k_xp_2003.htm ie.e:

  • click on Internet Protocol (TCP/IP) and Properties.
  • click Advanced, and select the WINS tab.
  • disable NetBIOS over TCP/IP.

change is immediate and you do not need to reboot the windows server.

"The application has failed to start because the application configuration is incorrect. Reinstalling the application may fix the problem."

Try installing [1]

NTLMv2 vs NTLMv1

Alfresco supports NTLMv2 when it is acting as the authoritative authentication provider. However, the NTLMv2 protocol does not allow Alfresco to pass authentication credentials through to Active Directory. When synchronizing with Active Directory, Alfresco does not import passwords because they are encrypted. Since Alfresco does not contain the Active Directory authentication credentials, it cannot implement NTLMv2 which protects against such man-in-the-middle scenarios. Alfresco recommends using Kerberos for situations where you might consider NTLMv2.

Additional information is on Alfresco_Authentication_Subsystems#Configuring_against_Active_Directory

An alternative is to authenticate using NTLMv1 and passthrough. See http://technet.microsoft.com/en-us/library/cc960646.aspx on how to setup the client to use NTLMv1

Kerberos on Java 5 with Windows 7 and 2008

NOTE: Alfresco Enterprise 3.2+ is NOT supported on Java 1.5, but we provide this information for Community users who are running Alfresco on Java 1.5 and want to connect to CIFS using Kerberos from Windows 7 or 2008 client.

As per https://issues.alfresco.com/jira/browse/ETHREEOH-3225?focusedCommentId=53568&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_53568 , Java 1.5 does not support RC4-HMAC encryption. To overcome this, while setting up the Alfresco Kerberos account you need to select "Use Kerberos DES encryption types for this account" to allow DES to be used for Kerberos encryption.

This configuration though won't work by default on Windows 7 and 2008 ( see http://support.microsoft.com/kb/977321 ) because the DES encryption is disabled by default. In order to have this working you'll need to enable the DES encryption by setting the following group policies (or local registry settings):

  • In the Group Policy Management Console (GPMC) by running 'gpedit.msc', and locate the following location:
  • Computer Configuration\ Windows Settings\ Security Settings\ Local Policies\ Security Options
  • Click to select the Network security: Configure encryption types allowed for Kerberos option
  • Click to select Define these policy settings and all the six check boxes for the encryption types.
  • Click OK
  • Close the GPMC.

OR

  • The group policy sets the SupportedEncryptionTypes registry entry to a value of 0x7FFFFFFF.
  • The SupportedEncryptionTypes registry entry is at the following location: HKLM\Software\Microsoft\Windows\CurrentVersion\Policies\System\Kerberos\parameters\


Back to Server Configuration

Personal tools
Download and go
© 2014 Alfresco Software, Inc. All Rights Reserved. Legal | Privacy | Accessibility