Troubleshooting

Users unable to connect

On-Premise Mac OS X based solutions

If all your users cannot connect then there are two broad likely causes.

A network problem preventing the DocMoto client accessing the DocMoto server.
The DocMoto server is failing to accept connections for some reason.

Testing for a network problem

Log in from the server machine
The first check to make is to try and log into the DocMoto server from the same machine. To do this you will need a DocMoto client installed on the same Mac as the DocMoto server.

If you can log in successfully then you have a network problem and should seek assistance from your network specialist.
Ping the server machine
If for any reason you cannot get access directly to the Mac running the DocMoto server then a good test is to "ping" the Mac running the DocMoto server. To do this go to one of the Macs where the DocMoto client cannot log in, open "Terminal" (which is in Applications) and type the following where "Mac server address" is either the IP address or network name of the Mac running the DocMoto server.
```
ping <mac server="" address="">
</mac>
```
For example, pinging IP address 192.168.2.220 would be:
```
ping 192.168.2.220
```
If the command returns a recurring line of the form "Request timeout for icmp_seq n" (where n is a number) then the server running DocMoto is inaccessible. This means you either have a network problem or the Mac itself is not running.

Testing for a DocMoto server problem

If the network and the Mac running the DocMoto server are fine then there could be an issue with the DocMoto server.

In the vast majority of cases the solution is to reboot the Mac.

A preliminary (though not necessarily conclusive) check can be made by looking to see if the DocMoto server and the backed database PostgreSQL are running.

To check open the "Activities Monitor" in "Utilities" within "Applications". Choose "All processes" from the drop down list. Entering "post" in the filter will show if PostgreSQL is running. You should see one or more, (it is quite normal to see several) postgres processes listed.

To check for the DocMoto process enter "doc" into the filter and you should see a single process listed called docmotoserver.

If either process is missing re-boot the Mac.

Common PostgreSQL related issues

PostgreSQL database stopped or has been re-started
The DocMoto server maintains connections for each connected user with the backend PostgreSQL database. If for any reason PostgreSQL is stopped or re-started without re-starting the DocMoto server user's connections will be broken.

If the PostgreSQL database is the problem users will typically see a message such as Unable to connect to the DocMoto server. (Socket::Closed)

Some other products such as Apple's Remote Desktop also use PostgreSQL and can occasionally restart it. The other most common reason for PostgreSQL to either stop or be re-started is a server administrator or even a backup product.

If PostgreSQL has been stopped or restarted you will often find a message such as the following in the system logs:
```
com.apple.launchd[1]: (com.edb.launchd.postgresql-9.1[66]) Exited: Killed: 9
```
The resolution is to restart the Mac. This will ensure all the correct PostgreSQL and DocMoto processes are re-started in the correct order.
PostgreSQL default connection limit exceeded

Whenever a user connects to DocMoto there is a corresponding connection with the PostgreSQL database.

Under normal operation this connection is closed when the user logs out of DocMoto. However when users move around, typically with MacBooks (taking them home, going to meetings etc) it can happen that stray connections are left open. The DocMoto server will clean these up eventually, but in very rare cases the number of connections left open exceeds the default (200) for a PostgreSQL database.

If the number of connections is exceeded the DocMoto server will refuse connections. Users will typically see a message such as Unable to connect to the DocMoto server. (Socket::Closed)

The resolution is two fold. Firstly the likelihood of this happening is dramatically reduced if the DocMoto server is restarted overnight. (You should be doing this anyway as part of the backup procedure). This will clear any stray connections left open.

Secondly a simple Mac restart will get the DocMoto server accepting connections again.

Note: We do not recommend adjusting the maximum number of users a PostgreSQL database can accept before discussing it first with CHLSoftware support.
PostgreSQL database refuses to re-start
If user can still not connect after a re-start then check that the postgres and docmotoserver services have started. If not then consult system logs for reasons why they might be failing.

One reason we have experienced is the PostgreSQL user on the Mac being deleted. PostgreSQL needs this user to run. You can check for the presence of this user by looking in "Users and Groups" in "System Preferences". You should see a user called PostgreSQL listed.

Firewall Ports closed

Connections to the DocMoto server are usually on ports 3983 or 3984 (SSL). When connecting to a DocMoto server internally it is unusual to have the ports blocking the connection, though it can happen especially in larger organisations.

The most reliable test for a port being open is telnet.

To test for port 3983 (for example) simply type the following in Terminal.

telnet <mac server="" address=""> 3983
</mac>

Where "Mac server address" is the address of the DocMoto server. For example:

telnet 192.168.2.331 3983

Or if you are on the DocMoto server Mac then you can type:

telnet localhost 3983

If the DocMoto server is accessible you will receive something like the following back:

Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.

If the DocMoto server inaccessible you will get a message something like the following:

telnet: Unable to connect to remote host

If you do decide that a firewall is blocking communication on either port 3983 or 3984 you will need to adjust your firewall's settings.

Hardware issues

Hardware issues can result in a DocMoto server exhibiting apparently random behaviour. Typically users being intermittently allowed access, very slow response, or incomplete data sets being returned to the DocMoto client.

By far the most common hardware issue is restricted or error prone access to the disk drive. If the DocMoto server or PostgreSQL database cannot access the base storage for any reason then highly inconsistent behaviour will be observed.

Hardware issues are even more likely when storage is on external drives, particularly those using Thunderbolt.

If you suspect a hardware related issue we suggest two basic checks.

Check any cabling connecting the hard drive to the Mac server. Cables can work lose, they can also be of poor quality. Always use high quality cabling.
Check the system logs. If there is a problem accessing a drive there will usually be an entry in a system log.

Removing access permissions to the DocMotoConfig folder

Though invisible to non-administrators the DocMotoConfig folder contains some files that all users must access in order to login to a DocMoto server correctly.

If access is removed from the folder users will get an error similar to the following: You have lost your connection' and clicking on "Details" will reveal a "403 Forbidden" message.

If you experience this issue check that the group "Users" have "Read Only" access to the DocMotoConfig folder.

PostgreSQL Corruption

Whilst being one of the most reliable open source products available PostgreSQL is not immune from corruption. A corrupt database usually manifests itself in a progressively slower user experience. A slow down in searches and directory listings being particularly noticeable.

Restarting the Mac server often clears the problem but over time the system slows down again.

The reason being that most PostgreSQL corruptions usual entail SQL queries not returning. But instead remaining in process and preventing other queries from executing. This accounts for the slow down experienced by users.

PostgreSQL corruptions are usually caused by a hardware fault. Generally at the disc access level. So if you do have a corruption problem you may well have a hardware problem.

If you do suspect that you have a corrupt PostgreSQL database it is worth looking at the PostgreSQL logs.

On OS X you will usually find the log files in /Library/PostgreSQL/X.X/data/pg_log (where X.X is the version number of PostgreSQL, eg 9.2). You will need to access them via terminal and be logged in as a super user using the sudo -s command (see below).

Reporting a Problem

If you need to report a problem with your DocMoto server it is always helpful to include the server logs. The log files we are interested in are located in /var/opt/docmoto/. You will need to access them via terminal and you will need to be a super user. So you must use the sudo -s command ie:

sudo -s

Then to move to the log file directory.

cd /var/opt/docmoto

Server logs come in pairs, DocMotoServer.XX.XX.XX.log which contains any errors and ServerRequest.XX.XX.XX.log which lists all the activity. When reporting a problem always include both.

A set of log files is created whenever the server is started, and terminated whenever the server is stopped.

Always include the log pairs just prior to any restarts. You can identify them by the date and time, which is part of the file name.

DocMoto hosted solutions

If you are unable to connect to a hosted DocMoto server then the most likely problem is a fault with your network.

You should check that your router is allowing outgoing connections on port 3984. The "telnet" test described above can be helpful for this.

If you get You have lost your connection' and clicking on "Details" reveals a "403 Forbidden" message then check access permissions on DocMotoConfig as described above.

If problems persist you should contact CHLSoftware support.