File Server Configuration

From AlfrescoWiki

Jump to: navigation, search


SMB/CIFS, FTP and WebDAV access is available allowing the use of existing client software to access the Alfresco data store. This allows you to browse to the server using Windows Explorer or create a Network Place, for example.

Contents

[edit] Filesystem Configuration

The filesystems available to the various file servers are configured via the file-servers.xml file in the WEB-INF\classes\alfresco folder, or the file-servers-custom.xml file in the WEB-INF\classes\alfresco\extension folder, via the Filesystems configuration section.

There are now two types of filesystem included in Alfresco, the original repository filesystem and the new AVM/WCM filesystem. The repository shared filesystems are configured using the <filesystem> tag, and the AVM/WCM shared filesystems are configured using the <avmfilesystem> tag.

[edit] Repository Filesystems

The <filesystem name="..."> tag is used to create a repository filesystem with the specified name.

The filesystem requires a store name and root path. The default configuration creates an Alfresco filesystem using the following :- 

<filesystems>
 <filesystem name="Alfresco">
  <store>workspace://SpacesStore</store>
  <rootPath>/app:company_home</rootPath>
  [<relativePath>/My Space</relativePath>]
 </filesystem>
</filesystems>

The optional <relativePath> tag 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 pseudo files into the filesystem to provide URL link files that link to the web location of a CIFS folder, and/or special applications that run on the client side known as desktop actions. For more details on configuring desktop actions/URL files see Desktop Actions.

[edit] AVM/WCM Filesystems

The <avmfilesystem name="..."> tag is used to create an AVM/WCM filesystem with the specified name.

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

<filesystems>
 <avmfilesystem name="STORE">
  <storePath>main:/</storePath>
  [<version>-1</version>]
  [<createStore/>]
 </avmfilesystem>
</filesystems>

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

The <createStore/> tag can be used 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 available stores as seperate shares you can use the following :- 

<filesystems>
 <avmAllStores/>
</filesystems>

The <avmAllStores/> tag will create a shared filesystem for each available store using the same name as the store. The shared filesystems are writeable as they share the head version of the stores.

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

<filesystems>
 <avmfilesystem name="AVM">
  <virtualView [stores="normal,staging,author,preview"]/>
 </avmfilesystem>
</filesystems>

The <avmfilesystem name="..."> tag is used to create an AVM/WCM filesystem with the specified name.

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 <virtualView/> configuration tag has an optional attribute 'stores' that is 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.

  • 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 file-servers.xml. 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]
..

[edit] Home Folder Filesystem

The <homeFolder [name="..."]/> tag creates a dynamic repository filesystem that maps to the logged on users home space.

The name attribute 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.

[edit] AVM Share Version Mapper

The <avmVersionMapper/> tag 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 <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 <homeFolder .../> setting.

[edit] SMB/CIFS Server Configuration

The SMB/CIFS server is configured via the file-servers.xml file in the WEB-INF\classes\alfresco folder, in the CIFS Server configuration section. Site specific customisation of these default values is located in file \tomcat\shared\classes\alfresco\extension\file-servers-custom.xml

The server includes Java socket based implementations of the SMB/CIFS protocol that can be used on any platform. 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 existing Windows file server.

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

Some of the configuration values have a platforms attribute that allows a single configuration file to be used for multiple platforms. The configuration will only apply to the specified platforms, which can be a comma delimited list. Valid platform ids are linux, solaris and macosx.

The following configuration values are available for the SMB/CIFS server :-

  • <serverEnable enabled="true|false"/>

Enables or disables the CIFS server.

  • <host name="..." [domain="..."]/>

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 name attribute can use the special token of {localname} to use the local servers host name and generate a unique name by prepending/appending to it.

The domain attribute is optional, it specifies the domain or workgroup that the server belongs to. This defaults to the domain/workgroup of the server if not specified.

  • <comment>...</comment>

Comment that is displayed in various Windows information dialogs.

  • <broadcast>n.n.n.n</broadcast>

Specifies the broadcast mask for the network. This value is only required if the Java socket based protocols are being used.

  • <bindto>n.n.n.n</bindto>

Specifies the network adapter to bind the Java socket based interfaces to, if not specified the server will bind to all available adapters/addresses.

  • <tcpipSMB [platforms="..."]/>

Enables native SMB on port 445 that is used by Win2000 and above clients.

To enable native SMB support under Windows requires that the Windows native SMB support is disabled by editing, or creating, the following registry key :- 

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\NetBT\Parameters]
 "SMBDeviceEnabled"=dword:00000000
  • <netBIOSSMB [bindto="..."] [platforms="..."]/>

Enables the Java socket based NetBIOS over TCP/IP implementation.

The bindto attribute optionally specifies the network adapter to bind to, if not specified NetBIOS will bind to all available adapters/addresses. Overrides the global bindto setting.

To enable the Java socket based NetBIOS implementation 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.

  • <hostAnnounce [interval="..."]/>

Enables announcement of the CIFS server to the local domain/workgroup so that it shows up in Network Places/Network Neighborhood.

The optional interval attribute specifies the announcement interval in minutes.

This value is only applicable when socket based NetBIOS over TCP/IP is enabled.

  • <WINS>

Specifies a primary and secondary WINS server to register the server name with when using the Java socket based NetBIOS interface.

Example :- 

<WINS>
 <primary>90.1.0.1</primary>
 <secondary>90.1.0.2</secondary>
</WINS>
  • <Win32NetBIOS [name="..."] [api="winsock|netbios"]/>

Enables the JNI based NetBIOS interface code under Windows; by default, api="winsock". On all other platforms this value is ignored.

The optional name attribute can be used to specify a different name for the server than the name specified via the <host> tag.

The optional api attribute specifies whether the JNI code uses the Win32 Netbios() API call or uses Winsock calls.

  • <Win32Announce [interval="..."]/>

Enables annoucement of the CIFS server to the local domain/workgroup so that it shows up in Network Places/Network Neighborhood.

The optional interval attribute specifies the annoucement interval in minutes.

This value is only applicable when the JNI based NetBIOS interface is enabled.

  • <sessionDebug flags="...,..."/>

Enables debug output levels for CIFS server debugging.

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

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


CIFS server debug flags
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

[edit] 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 in the file-servers.xml or file-servers-custom.xml configuration files :- 

     <tcpipSMB port="1445" platforms="linux,solaris,macosx"/>
     <netBIOSSMB sessionPort="1139" namePort="1137" datagramPort="1138" platforms="linux,solaris,macosx"/>

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

The firewall rules should then be setup 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

[edit] FTP Server Configuration

The FTP server is configured via the file-servers.xml file in the WEB-INF\classes\alfresco folder, or the file-servers-custom.xml file in the \tomcat\shared\classes\alfresco\extension folder, via the FTP Server configuration section.

[edit] Configuration Values

  • <serverEnable enabled="true|false"/>

Enables or disables the FTP server.

  • <port>...</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.

  • <bindto>...</bindto>

Specifies the address the FTP server binds to, if not specified the server will bind to all available addresses.

  • <rootDirectory>...</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/
  • <debug flags="...,..."/>

Enables debug output levels for FTP server debugging.

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

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

[edit] NFS Server Configuration

The NFS server is configured via the file-servers.xml file in the WEB-INF\classes\alfresco folder, or the file-servers-custom.xml file in the WEB-INF\classes\alfresco\extension folder, via the NFS Server configuration section.

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.

[edit] Configuration Values

  • <serverEnable enabled="true|false"/>

Enables or disables the NFS server.

  • <enablePortMapper/>

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>n</ThreadPool>

Set the size of the RPc processing thread pool. The minimum number of threads is 4, the default setting is 8.

  • <PacketPool>n</PacketPool>

Set 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>n</PortMapperPort>

Port number to run the portmapper service on. The default port is 111.

  • <MountServerPort>n</MountServerPort>

Port number to run the mountserver service on. The default is to allocate an available non-privileged port.

  • <NFSServerPort>n</NFSServerPort>

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.

  • <rpcAuthenticator>

Configures the user id/group id to Alfresco user name mappings that are used by the current RPC authentication implementation.

Specify the user name to user id/group id mappings using the <userMappings> section, each entry is specified using the <user name="..." uid="..." gid="..."/> tag. For example :- 

<rpcAuthenticator>
  <userMappings>
    <user name="admin" uid="0" gid="0"/>
    <user name="auser" uid="501" gid="501"/>
  </userMappings>
</rpcAuthenticator>
  • <debug flags="...,..."/>

Enables debug output levels for NFS server debugging.

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

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


NFS server debug flags
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

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.

[edit] NFS Gotchas

  • UID <==> GID. A bug in the NFS server (JLAN-11) transposes the GID and UID of the NFS client user meaning that Unix accounts that have a user-id that differs from the group-id will not gain authentication. The Alfresco-NFS server will deny them access. Unhelpfully, all the user will see is ls: /mnt/alfresco: Input/output error. This issue lasted this long presumably because so many Linux distributions create a new group for each new user, unless told otherwise. Though the bug is declared closed, it has yet to trickle down to SVN, and org.alfresco.filesys.server.auth.AlfrescoRpcAuthenticator.authenticateRpcClient(int, RpcPacket) still reads the gid before the uid.
  • 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 -oport=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.

[edit] WebDAV Server Configuration

The WebDAV interface is configured via the web.xml file in the WEB-INF folder.

WebDAV is enabled by default in the standard web.xml file via the following entries :- 

<servlet>
 <servlet-name>WebDAV</servlet-name>
 <servlet-class>org.alfresco.repo.webdav.WebDAVServlet</servlet-class>
  <init-param>
   <param-name>store</param-name>
   <param-value>workspace://SpacesStore</param-value>
  </init-param>
  <init-param>
   <param-name>rootPath</param-name>
   <param-value>/app:company_home</param-value>
  </init-param>
  <load-on-startup>5</load-on-startup>
</servlet>

<filter>
 <filter-name>WebDAV Authentication Filter</filter-name>
 <filter-class>org.alfresco.repo.webdav.auth.AuthenticationFilter</filter-class>
</filter>

<filter-mapping>
 <filter-name>WebDAV Authentication Filter</filter-name>
 <url-pattern>/webdav/*</url-pattern>
</filter-mapping>

<servlet-mapping>
 <servlet-name>WebDAV</servlet-name>
 <url-pattern>/webdav/*</url-pattern>
</servlet-mapping>

The default path to the WebDAV server is http://server:port/alfresco/webdav/.


Note that The Microsoft WebDav Client in various versions of windows doesn't correctly support port numbers in URL's. see http://greenbytes.de/tech/webdav/webdav-redirector-list.html#issue-basic-authentication

--Ckelloug

[edit] Troubleshooting

[edit] 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.

[edit] Native SMB collisions

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.

Note: This does not seem to work any more with Windows Vista.

[edit] CIFS Connection with Alfresco 2.1.1 distribution

Error : When setting up an Alfresco 2.1.1 Enterprise with Tomcat on Linux (Suse Open Linux 10.3), no CIFS connection can be made both from local system and from remote Windows XP Professional.

Fix: With the .WAR from Enterprise 2.1.1-Tomcat, the file-server.xml does not match the documented version.

  1. Remove all ":8080" from file-server.xml or overwrite the settings in the file-server-custom.xml, if installed on :80
  2. use "<servername>A" instead of "<servername>_A" as stated in the docs
  3. Remember to open the firewall ports on SMB, but no SMB-Server installation activated!
  4. For localhost connections - change the /etc/hosts entry on the alfresco mashine
from "127.0.0.1 <alfrescoServerName>A"
to "<real IP> <alfrescoServerName>A" (Example : 192.168.1.132 alf_testA

(Norgan 16:24, 11 March 2008 (UTC))

Back to Server Configuration

Retrieved from "http://wiki.alfresco.com/wiki/File_Server_Configuration"