I had to update my Windows 7 Virtual Machine this week in order to do some demo videos. It is always painful to renew my frustration with that operating system. I dug out my old list of gotchas related to connecting to Alfresco from a Windows machine. I updated them, and decided to post them here.
Most of these tips come from either the official Alfresco documentation or the Alfresco wiki, but some come from issue reports, experience, and hearsay. Some tips might be out-of-date. I submitted most of these tips as enhancement to the documentation.
CIFS is the correct name for the modern version of the smb protocol, as implemented by Microsoft, Samba, and Alfresco. CIFS is useful for connecting to Alfresco as if it were a file server on the local network. It is not very tolerant of network problems and latency, so it is only recommended to use with a geographically close server on a reliable network. There are also concerns with security of the CIFS protocol, so it is not recommended to use on an untrusted network.
Setting up Windows to talk to Alfresco over CIFS is pretty easy. Just use the Map Network Drive dialog with one of these connection strings:
- If Alfresco is serving CIFS directly (such as on a non-Windows server):
- If Alfresco is serving CIFS through Windows:
(The serverName is customizable in alfresco-global.properties cifs.serverName)
It is easiest to configure Alfresco as a CIFS server when running on Linux. If you are on Windows, then the Windows native CIFS server can get in the way. The Alfresco documentation discusses this, but it is a bit scattered so you will have to search for it. Details are below under "Stop Native and Alfresco CIFS Conflicts".
- Can you use the same username and password to login through Alfresco Share?(http://<host_name>:<alf_port>/share)
- Are you certain that the Alfesco service has finished loading?
Look for a "Server startup in . . . ms" message in the log file.
- Does it work if you use the IP address instead of the hostname?
Try changing the cifs.serverName property and restarting Alfresco.
If Alfresco is running on a Windows Server:
- Does the Alfresco share show up with "nbtstat -n" on the server?
- Does the Alfresco share show up with "nbtstat -na <server ip>" on a client machine?
- Are you trying to mount a network share to Alfresco on the server running Alfresco?
See the section "CIFS to Local Server".
- In Windows Firewall Advanced Settings -> Inbound Rules -> File and Printer Sharing enabled all NB-Name-In and NB-Session_In rules. See the section on Native and Alfresco CIFS conflicts.
- Verify that the DLLs which handle the hand-off between the native CIFS server and Alfresco are available to Alfresco (usually in C:\Alfresco\Tomcat\bin):
- Can Alfresco bind to the necessary ports?
Look for errors in the Log file related to java.net.BindException errors. If there are errors, see the section on "Stopping Native and Alfresco CIFS Conflicts".
CIFS to Local Server
Use Case: I want to connect to my locally installed Alfresco server via CIFS and I am running Windows 7 (or Windows Server 2008)
Symptoms: The CIFS server appears on my network list, however when I try to connect I either get timeouts or it prompts me for username and password which don’t work. I get a message stating "The specified network password is not correct."
Cause: Using local connections, Windows uses a loopback connector rather than the network connection. Because the firewall config required for external access to the CIFS share of an Alfresco system deployed on Windows 7 (or Windows Server 2008) does not affect loopback connections, it does not block the internal Windows CIFS server. So when attempting to connect to the local CIFS share, Windows is resolving to the native implementation rather than to the Alfresco implementation of CIFS. This is why you can’t connect.
Workaround: Create a fake entry in your hosts file for the CIFS share that does not resolve. E.g.192.168.192.192 <the_name_of_my_cifs_share> This causes a DNS mismatch that makes SMB fall back to NetBIOS resolution, allowing connection to proceed to the Alfresco CIFS share.
Stop Native and Alfresco CIFS Conflicts
When running Alfresco on Windows, sometimes it is helpful to deactivate the Windows CIFS service to allow the Alfresco socket code to bind to port 445. This eliminates problems with the handoff between Windows and the Alfresco file shares. Alfresco will need to be configured to serve CIFS directly. Once that configuration is made, 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."
In order to stop native SMB being used when the Alfresco CIFS server is being run under Vista, Windows 2008, or Windows 7, the firewall rules can be updated to block inbound connections on port 445. To set up the Windows firewall on the system running the Alfresco CIFS server:
- Run the Windows Firewall with Advanced Security application:
Vista: Go to Control Panels > Administrative Tools
Windows 2008: Go to Start > Administrative Tools
- Click on the Inbound Rules item in the left hand column.
- 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)
- 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.
This works on Windows 2003 Server. I'm not sure about other versions of Windows.
Switch off Windows NetBIOS and native SMB by creating this registry key:
Reboot the system after creating the key.
Run a Dedicated Network Interface
Another option is to setup a dedicated network interface for Alfresco. This allows the server to serve Windows shares in parallel to serving Alfresco shares. You will create an alias TCP/IP address and bind the Alfresco CIFS/NetBIOS subsystem to that 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.
- 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 so that Alfresco can bind to those ports.
- If you see something listening on this interface before you have started Alfresco, then you should deactivate the Windows CIFS services on that interface.
- Make sure you also tell alfresco to bind to this new IP following the Alfresco configuration changes in File Server Subsystem.
NTLM is useful for Single Sign-on of Windows Shares (SSO).
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.
To authenticate using NTLMv1 set this registry key on your client machines:
- [HKLM\SYSTEM\CurrentControlSet\Control\Lsa] "LmCompatibilityLevel"=dword:00000001
Failure of NTLM Logon on Machines Running Windows7/IE8
Problem Description: It has been observed in some cases that machines running Windows7/IE8 are unable to logon via NTLM, whereas XP machines running IE7 work fine.
Solution: This problem is most likely caused by increased default security in Windows 7 (and Vista and Windows Server 2008) that will only negotiate NTLMv2, whereas Alfresco only understands NTLMv1. Previous versions of Windows (XP) would drop back to NTLMv1 if NTLMv2 failed.
- On one of the Windows 7 clients, go to Control Panel->Administrative Tools->Local Security Policy.
- In the left pane, navigate to Security Settings->Local Policies->Security Options.
- In the right pane, find "Network Security: LAN Manager authenication level".
- By default, it's set to "Send NTLMv2 response only. Refuse LM & NTLM". Try setting it to "Send LM and NTLM - use NTLMv2 session security if negotiated". This will allow Windows 7 to use the more secure NTLMv2 when available, but drop down to NTLMv1 for Alfresco.
- If these machines are in a domain, it may be possible to change this setting on all of them via the group policy editor on the domain controller.
WebDAV allows you to connect to Alfresco as if it were a fileserver over the standard web protocols.
WebDAV works over the normal HTTP protocol, and since it is usually used to mount a drive over the general Internet, it is highly recommended to use SSL encrypted HTTPS connections. Since version 4.0, Alfresco is configured out-of-the-box to accept HTTP connections on port 8080 and HTTPS connections on port 8443, but many administrators will use firewall rules, a port redirect, or a custom Tomcat configuration to allow connections on the standard ports of 80 (HTTP) and 443 (HTTPS).
In theory, setting up a WebDAV network drive on Windows is simple:
- Open Windows Explorer
- Righclick on ‘Computer’
- Go to ‘Map Netowrk Drive’
- Choose the drive letter
- Use this link for an encrypted connection to WebDAV (if you are using the standard port of 443, drop the :<alf_port>)
- Enter your credentials
Alfresco WebDAV currently only understands HTTP Basic Auth, so this registry change should be made on Windows Clients connection to Alfresco:
- [HKLM\SYSTEM\CurrentControlSet\services\WebClient\Paramaters] "BasicAuthLevel"=dword:2
- Restart the WebClient service, or reboot
In order to have Windows connect to a secure WebDAV share, you will need a valid certificate. The one included in Alfresco is self signed. You can use a self signed certificate by installing it into the Certificate store of each client computer. I found that I had to install the certificate into the Trusted Root Certificate Authorities store. The Personal and Intermediate Certificate Authority stores appear to be ignored when mounting a drive. Also, Windows 7 does not give a certificate error--it just asks repeatedly for the username and password and fails silently.
- Can you use the same username and password to login through Alfresco Share?
- Are you certain that the Alfesco service has finished loading?
- Does it work if you use the IP address instead of the hostname?
- Can you make a cleartext connection over HTTP?
- Can you use a web browser to browse the folders, using either HTTP or HTTPS?
i.e. if you put the connection URL in the web browser, does it ask you to login and then show you the folder tree?
- Do you have some type of SSO set-up that is getting in the way?
- Try selecting Connect Using Different Credentials, and confirm the username and password.
- Add your Alfresco server IP to the Trusted sites list in Internet Properties.
- Make sure the Webclient Service is running:
- Start the Webclient service
Alfresco has an open source implementation of the SharePoint Protocol (thank you EU anti-trust regulators for forcing Microsoft to release the specifications). This allows Alfresco to stand in for a SharePoint server for most of the collaboration functions in Microsoft Office. Specifically, applications such as Microsoft Word can save files to Alfresco Share sites, read files from Alfresco Share sites, and interact with the version history to track changes and compare files.
Alfresco 4.0 can handle most SharePoint requests originating from Office 2007, Office 2008 (Mac), Office 2010, and Office 2011 (Mac). I haven't personally tested Office 2013, but I think someone would have complained to me by now if it didn't work. I have connected to Alfresco from within Word, Excel, PowerPoint, and Outlook. There is a list of features not supported in the documentation.
This quickstart is a good guide to the functionality with Office 2007. I should note that in order to create a SharePoint enabled Document Workspace, the creation needs to be initiated from within Microsoft Office. It isn't a standard Alfresco Share site, and can't be created from within the Share Interface. In Office 2010 Microsoft discontinued the concept of a Document Workspace, so the interaction is with a standard Share Site. The Meeting Workspace features in Outlook also appear to be gone in Office 2010.
The official documentation also has decent instructions for setting everything up, but most of that isn't needed for out-of-the-box functioning. If you are trying to work with Office 2010, understand that Windows 7 already includes the Microsoft patch for Web Folders, so that isn't needed.
A few things that are helpful to know when trouble shooting SharePoint connections with Alfresco:
- SharePoint Protocol is an incompatible implementation of WebDAV, so most of the same information discussed there applies here.
- The Alfresco module is called VTI, and Alfresco embeds a Jetty server to handle the connections.
- The default port is 7070.
A few things to know about configuring the Alfresco server to act as a SharePoint server:
- There are links in Alfresco Share to "Edit Online", which will open a file in Microsoft Office using the SharePoint protocol. The URLs for those links are constructed with the vti.server.external.host setting in the alfresco-global.properties file. That is the only configuration I needed for the server to function correctly.
- By default, Alfresco does not encrypt the SharePoint Protocol. The documentation has instructions for setting up encryption, but it is pretty involved. If you encrypt the protocol, you should not change the port to the standard SharePoint port for encrypted communication. Alfresco expects port 7070 in a lot of places, and it is likely that Alfresco will stop working if you change the port. I haven't had Windows or Office have any problems detecting encryption on port 7070 and adapting.
And important information for connecting to Alfresco from Windows using the SharePoint Protocol:
- The "Edit Online" links only appear in Alfresco Share when:
- the content is in a Share site (not in other parts of the repository)
- the content MIME type is associated with the SharePoint Protocol
- the browser is Internet Explorer or has the Microsoft Office Plugin (installed into Firefox during Microsoft Office installation)
- If you have not added your Alfresco server as a trusted site in Windows, you will get a warning on every download about the risks of running content from the network.
- Remember to tell Windows to remember your login credentials.
- If Windows keeps asking for your credentials even after you told it to remember, then you might be hitting the bug documented here. That article explains that Windows sees hostnames with periods as originating on the Internet, which includes IP addresses for the local network. It interprets these hosts as being untrusted even if you have added them to the list of trusted sites, so it does not check if there are matching stored credentials. It mentions a registry setting that removes that check for Windows 7, but I think an easier solution is to use a local network hostname (no periods) instead of an IP address. I setup a quick mapping in C:\Windows\System32\drivers\etc\hosts. No reboot required.
- Alfresco's implementation of the SharePoint Protocol only knows HTTP basic auth, so like explained for WebDAV connections, a registry setting needs to be changed. This includes the key for WebClient and Office Internet connections:
- [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\WebClient\Paramaters] "BasicAuthLevel"=dword:2
- [HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Common\Internet] "BasicAuthLevel"=dword:2
If everything is working properly, then in Microsoft Office's dialogs for "Open", "Save As", "Publish" (Office 2007), and Save to SharePoint (Office 2010), you can enter the Alfresco SharePoint URL, and browse Alfresco Share sites:
I should mention that there are a number of add-ons and partner solutions that help Alfresco integrate with a Microsoft Windows environment. Also, the Alfresco Workdesk product has additional integration with Microsoft Office that I have not discussed here.
In the Alfresco101 YouTube channel, there is a Community Edition playlist with a bunch of tutorial videos in the Community Edition How-to Series. I am about to post a short tutorial video demonstrating the SharePoint protocol connection (that video is what prompted this post).