The official documentation is at: http://docs.alfresco.com
Table of Contents
- 1 Objectives
- 2 Introduction
- 3 Authentication
- 4 Planning
- 5 Domain Controller Changes
- 6 Alfresco Server Changes
- 7 Trouble shooting
- 8 Running Alfresco on Windows
- able to access Alfreso share(s) on Ubuntu natively from any Windows or Linux client
- able to access existing CIFS file system on the server which hosts Alfresco
- no turning off Windows native SMB other such hacks
Applies to Alfresco version 4.2e and above
The following details were verified on Ubuntu 10.4.
The Domain Controller in this case was Windows Server 2008 R2 and Alfresco was configured for Active Directory synchronization and Kerberos authentication.
This is the only authentication arrangement detailed, but adjustments for other schemes should be easy to work out. For example, if AlfrescoNtlm is used, then log on is required and only Alfresco accounts can be used.
Alfresco CIFS file system can be bound to a second IP address on the server network interface. When running on Linux, the required adjustments are straightforward.
When running on Windows, the adjustments are complicated by the need to make network configuration changes.
Details on how to add a second IP address on Linux are based on Ubuntu but are applicable to most Linux distributions used to run Alfresco.
So as not to detract from the relative simplicity of the Linux case, details specific to Windows are given separately , see 'Running Alfresco on Windows' below.
Details on how to configure authentication are given in Alfresco Authentication Subsystems.
Successful installation of Alfresco CIFS file system depends on getting authentication set up correctly.
For the verification, the authentication chain in alfresco-global.properties was:
Relevant authentication settings for CIFS are:
With this configuration, Kerberos performs Single Sign On (SSO), so only domain accounts have access to the file system.
AlfrescoNltm, which requires user logon, can also be used as a lower security level alternative.
Having a DNS host entry for the CIFS file system IP address is also a key component of getting authentication to succeed.
Details on how to configure this on Windows is given below.
Determine the address to be assigned for the file system.
It is recommended to use an available address in the valid range for the LAN segment to which the interface is connected.
The examples below will use 192.168.2.21.
The Alfresco CIFS file system has a server name which must be distinct from the host server name so the existing Samba CIFS shares can be accessed too.
There is a convention of appending an A to the host server name, so for example, 'server1' becomes 'server1A'.
Beware there is 15 character length limit for server names dictated by NetBIOS.
Domain Controller Changes
Bring up DNS Manager (Administrative Tools -> DNS).
On the left pane, expand the Host node. Expand 'Forward Lookup Zones'. Expand the node with the domain name eg mycompany.local.
On the right pane should be of DNS entries, with 'Host(A)' ones predominating. Add a host entry for the new Alfresco file system server as follows.
Left click on the domain name node and select 'New Host (A or AAAA)...'.
In the Name field, enter the Alfresco CIFS file system server name as determined in the planning stage eg 'server1A'.
In the IP address field, enter the Alfresco CIFS file system IP Address. Make sure 'Create associated pointer (PTR) record' is ticked.
Click 'Add Host' button and dismiss the confirmaton dialog.
To check the new DNS entry, open a command prompt and type 'nslookup <server-name>' eg 'nslookup server1A'.
The response, at the end, should identify the correct fully qualified domain name and address eg 'Name: server1A.mycompany.local \ Address: 192.168.2.21'
To check the PTR entry, type 'nslookup <server-ip-address>' eg 'nslookup 192.168.2.21'.
The response should be identical to the first one.
Alfresco Server Changes
Details will depend on distribution and personal taste, but there is plenty of advice on how to add a second IPv4 address to an interface on the internet.
Note that no gateway needs to be configured, so leave blank if a field for this appears on a properties form.
After setting the second IP address, a network restart is required eg. on Ubuntu > sudo service network-manager restart
It may take a while for the new address to come online.
Be aware that Firewall changes may required to allow external access on tcp ports 139, 445, 1139 and 1445 and udp ports 137, 138, 1137 and 1138.
Note that there is no requirement to add an entry in the /etc/hosts file for the new server. It should be resolvable by DNS.
cifs for Linux using server name 'server1A' and IP Address '192.168.2.21' as examples:
Note that all SMB ports are reassigned from their default values. This is not to allow Alfresco to run from a normal user account, but to ensure there are no port binding conflicts which prevent the file system from starting.
Note you may also wish to set 'cifs.sessionDebug=NetBIOS,State,Tree' for debugging connection progress.
Refer to Linux section on Running SMB/CIFS from a normal user account
Note that the PREROUTING rules have more details to distinguish the second IP address from the first ie. a --dst parameter and an IP address in the --to-destination value:
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 445 --dst 192.168.2.21 -j DNAT --to-destination 192.168.2.21:1445
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 139 --dst 192.168.2.21 -j DNAT --to-destination 192.168.2.21:1139
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 137:139 --dst 192.168.2.21 -j DNAT --to-destination 192.168.2.21:1137-1139
iptables -t nat -A PREROUTING -i eth0 -p udp --dport 137:139 --dst 192.168.2.21 -j DNAT --to-destination 192.168.2.21:1137-1139
'eth0' in this example is the interface and only needs to be specified if there is more than one in use.
Do not forget to make the iptables changes persistent.
Can you ping the new IP Address both locally and externally?
If not, check the configuration changes made for the second IP address. Was the network service restarted? Are the interfaces enabled and connected?
Can you ping the new IP Address by using the server name both locally and externally?
If not, check the DNS configuration changes. Check that the DNS server is running.
Can you telnet locally to ports 1139 and 1445 refering to the second IP address by server name eg > telnet server1a 1445?
If not, check the CIFS file system started and if it did, subsequent port binding problems did not cause it to stop running. Note you will need to turn on debug logging to investigate.
Can you telnet externally to ports 139 and 445 refering to the second IP address by server name eg > telnet server1a 445?
If not, check the iptable changes > sudo iptables -L -t nat -v. Also check if a firewall is preventing access. Include the udp ports in your check.
Note that port redirection is not available on the Alfresco server itself, so iptables configuration must be tested from an external location.
If all the above tests for network functionality are successful, then the next concern is authentication.
If using Kerboros, make sure you logged in with a domain account when trying to connect to the file system.
Also reference the server by name, not IP address eg. //server1a/alfresco not //192.168.2.21/alfresco.
Also test that it is possible to obtain a Kerberos ticket for the server account eg. cifs/server1a.mydomain.local@MYDOMAIN.LOCAL.
Samba client (smbclient) is likely to be already installed, but is readily available if not. The client is run on the command line and provides FTP-style access to the Alfresco CIFS file system.
It is useful for testing and debugging CIFS as it provides a large number of options and supports Kerberos authentication.
On the Alfresco server itself, use the -p parameter to specify port 1139 for the connection. From an external server this is not necessary as the iptables will do network address translation.
Here is what the smbclient command should look like on the Alfresco server when using Kerberos authentication:
smbclient -k -port 1139 -U <domain-username> \\\\server1a\\alfresco
If successful, smbclient should automatically log in and display an 'smb' prompt.
To debug, add parameter '-d 5' for the highest debug level.
You will see with debugging turned on that the default Samba config file is read to provide environmental data. You can specify an Alfresco-dedicated config file if desired, eg. for 'smba.conf' use '-s /etc/samba/smba.conf'.
Note that when using Kerberos authentication, every Linux client which connects to the Alfresco CIFS file system will need Kerberos client installed and configured in just the same way as performed on the Alfresco server.
Linux File Manager
Any Linux file manager is likely to provide a 'Connect to Server...' option and this allows connection to the Alfresco CIFS file system for every day use.
When using Kerberos authentication, every Linux client which connects to the Alfresco CIFS file system will need Kerberos client installed and configured in just the same way as performed on the Alfresco server.
This has been verified using Nemo v2.0.8. From the top menu, select File ->'Connect to server 'and a dialog pops up. Enter the server eg. 'server1a' and select from the Type options 'Windows share'. For Share enter 'alfresco'.
Complete the domain User Details and hit the 'Connect' button. The Alfresco share top level folders and files should be displayed.
Running Alfresco on Windows
Alfresco is running on Windows with native SMB running at the same is more complicated than with Linux because SMB port 449 is then bound by the operating system on every interface including the one used by Alfresco.
The solution is to arrange a network route to the Alfresco CIFS file system which performs port redirection, in this case, from port 449 to 1449.
Some general directions on how to do this are presented here, but the details depend on the existing network configuration which will be different in every case.
If the existing network configuration has Virtual LAN (Vlan) capability, then a good choice is to set up a new Vlan on the firewall/gateway and connect the Alfresco server to that Vlan.
If using a Vlan is out of the question, then a real LAN will need to be deployed instead.
Beware, the real LAN requires provisioning a switch and 2 new interfaces compared to the Vlan option which only adds one interface to the Alfresco server.
Note the new LAN can also be employed for Web traffic, which allows assigning standard ports 80 for HTTP and 443 for HTTPS.
The firewall/gateway will be configured to act as a gateway from the existing LAN to the the Alfresco CIFS LAN.
For all Alfresco ports in use, the gateway needs to perform source address translation on the outgoing interface so the Alfresco server can send responses back to the gateway.
The source address to be assigned is therefore the IP address of the gateway on the outgoing interface.
In the case of port 445, the gateway also need to perform port fowarding, translating port 445 to 1445.
Here is an excerpt from the iptables of a gateway showing the rules added for the new LAN.
For the following excerpt:
vlan2 and vlan3 are the incoming and outgoing interfaces respectively. For a real LAN, they might be eth1 and eth2.
the vlan2 valid address range is indicated by '192.168.1.0/24'
the Alfresco CIFS file system is bound to 192.168.2.21
the gateway outgoing interface address is 192.168.2.1
microsoft-ds = 445
netbios-ns = 137
netbios-ssn = 139
Chain PREROUTING (policy ACCEPT)
target prot opt in out source destination
DNAT tcp -- vlan2 any anywhere 192.168.2.21 tcp dpt:microsoft-ds to:192.168.2.21:1445
Chain POSTROUTING (policy ACCEPT)
target prot opt in out source destination
SNAT udp -- any vlan3 192.168.1.0/24 192.168.2.21 udp dpt:netbios-ns to:192.168.2.1
SNAT tcp -- any vlan3 192.168.1.0/24 192.168.2.21 tcp dpt:netbios-ssn to:192.168.2.1
SNAT tcp -- any vlan3 192.168.1.0/24 192.168.2.21 tcp dpt:1445 to:192.168.2.1
The gateway in this case was Zentyal, so the configuration was entered from a console.
Here is how these rules would be entered from the command line:
sudo iptables -t nat -A PREROUTING -i vlan2 -p tcp --dport 445 --dst 192.168.2.21 -j DNAT --to-destination 192.168.2.21:1445
sudo iptables -t nat -A POSTROUTING -o vlan3 -p udp -s 192.168.1.0/24 --dport 137 -j SNAT --to 220.127.116.11
sudo iptables -t nat -A POSTROUTING -o vlan3 -p tcp -s 192.168.1.0/24 --dport 139 -j SNAT --to 18.104.22.168
sudo iptables -t nat -A POSTROUTING -o vlan3 -p tcp -s 192.168.1.0/24 --dport 1445 -j SNAT --to 22.214.171.124
The new interface on the Alfresco server will need to be configured. Bring up the 'Internet Protocol Version 4(TCI/IPv4)' Properties for the interface.
In the 'General Tab' Set IP Address and Netmask. Leave the other fields empty.
Click Advanced... link and select WINS tab. Select 'Disable NetBIOS over TCP/IP'
One other thing to consider is to what Network Location the new interface will be assigned by the operating system. By default, it will be assigned to the 'Public' location.
Opening up ports in the Public firewall is not desirable.
Unfortunately, there is no convenient user interface provided to change the location. I has to be done by changing the local Group Policy and the only other location offered is 'Private'.
Here are the steps to change the Unidentified Network location:
To do this on your local server , follow these steps:
1. Start --> run --> MMC --> press enter
2. In MMC console , from menu file select Add/Remove Snap-in
3. Select Group Policy Object editor --> Press Add --> select Local computer --> press OK -->press OK
4. Open Computer configration -->Windows Settings -->Security Settings -->select Network list manager policies
on the right Side you will see options for :
double click -->Unidentified networks
Then you can select the option to consider the Unidentified networks as private
cifs for Windows using server name 'server1A' and IP Address '192.168.2.21' as examples:
Find this file in the Alfresco installation at location tomcat\webapps\alfresco\WEB-INF\classes\alfresco\subsystems\fileServers\default.
The tcpipSMB and netBIOSSMB beans have a 'platforms' property that needs to updated to include windows eg. see last property in following example
Windows-specific Tomcat command-line parameters
Tomcat command-line parameters to consider adding:
- Identify Kerberos configuration: -Djava.security.krb5.conf=%PROGRAMDATA%//MIT//Kerberos5//krb5.ini
- Kerberos AD interoperaton: -Dsun.security.krb5.msinterop.kstring=true
- Memory allocation. Try, if 4G available -XX:MaxPermSize=256M -Xss1024K -Xms1G -Xmx2G
- Prefer using IPv4 stack to avoid issues with SMTP. Use -Djava.net.preferIPv4Stack=true