This TechNote provides a set of instructions on how to diagnose some FTP (File Transfer Protocol) connection/edit/publish problems that Contribute users can experience. To test an SFTP connection, see Testing SFTP functions using command line (tn_19564).

For more troubleshooting resources, see FTP Troubleshooting and Resources (tn_18932).

Setup

Testing FTP functions requires a command line FTP tool. Both Mac OS X and the Windows operating systems come with a command line FTP tool. Additionally, you use a test file for testing the FTP and web server.

  1. Create a test HTML file to upload during these tests. Copy and paste the following into a text file and name the file test.htm:



    <body > <p>This is a test file used during FTP tests.</p> </body>
  2. Launch the command line tool.
    • Windows:
      1. Click Start, and then choose Run.
      2. Type cmd in the Run dialog box.
      3. Click OK. The Command Prompt window opens, which you use to communicate with the MS-DOS operating system. (The Command Prompt is sometimes also called the DOS prompt.)
    • Mac OS X:
      1. Launch the Terminal found in the Utilities directory within the Applications directory (HD>Applications>Utilities>Terminal).
  3. Place the test.htm file in your command prompt home directory. Determine that location as follows:
    • Windows: The first  line in the Command Prompt window indicates the home directory. This directory is usually C:\Documents and Settings\<user name>.
    • Mac OS X: Within Terminal, run pwd (print working directory). This directory is usually Users/<user name>.
  4. Verify that the test file is in the current directory.
    • Windows:
      1. Type dir in the Command Prompt window and see if test.htm is among the files listed.
      2. If test.htm is not listed, then move the file to this folder and repeat the dir command to verify the location of the file.
    • Mac OS X:
      1. Type ls in the Terminal window and see if test.htm is among the files listed.
      2. If test.htm is not listed, then move the file to this folder and repeat the ls command to verify the location of the file.

Basic operational tests

These operations test the FTP server for basic things like the ability to connect and transfer data, and checks file permissions. To use a real-world metaphor, these commands test to see if the "lamp with the burned out light bulb is plugged in." Type these commands in the command line tool as mentioned in step 2 above.

Connect to the server and log in

  • What's tested: This command tests if the server is live and reachable, and if the user name/password is correct.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code ). Line numbers are provided only for reference and aren't present in the window.



    1: ftp <server>

    2: User: <username>

    3: 331 Password required for server.

    4: Password: <password>

    5: 230 User <username> logged in.

    6: ftp>
  • Success: User is prompted for password. If password is correct, ftp> prompt appears.
  • Failure: You are unable to connect to the server.
  • Resolution:
    • If you are not prompted for your login (you do not see line 2), investigate whether the server is down, whether you have the correct server name, or whether the firewall/proxy is not allowing a connection.
    • If you are not prompted for your user name (you do not see line 3), investigate your login information. (It's possible that the server does not recognize the user name.)
    • If you are not logged in (you do not see line 5), investigate your password (the server does not recognize your password).

Get a directory listing

  • What's tested: This command tests data transfer capabilities. If the FTP command line appears to freeze after the "dir" command, there is most likely a problem with establishing a data connection. Not having the appropriate passive or non-passive mode set in the FTP client can cause this issue. Firewalls and proxies that block the incoming/outgoing data connection can also cause this problem.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code).



    ftp>ls or (depending on server type) ftp>dir 200 PORT command successful. 150 Opening ASCII mode data connection for /bin/ls. 09-08-04 04:59PM <DIR> _baks 08-26-04 04:19PM <DIR> _mm 09-08-04 04:59PM <DIR> _notes 09-08-04 04:59PM 678 test.htm 09-08-04 05:07PM 12 test.htm.LCK 226 Transfer complete. ftp: 367 bytes received in 0.02Seconds 50.40Kbytes/sec.
  • Success: Files in directory are listed.
  • Failure: Window freezes.
  • Resolution: Try manually setting (or unsetting) the passive mode in Contribute. Check for any firewalls or proxies that could be blocking connections. Resolve any data transfer problems before proceeding.

Create a directory

  • What's tested: This command tests if a directory can be created, and provides a place to put the test files. Choose a directory name that does not exist.



    Note: To fuction properly, it's necessary that Contribute can create directories.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code).



    ftp>mkdir macr_test 257 "macr_test" directory created.
  • Success: New directory is created.
  • Failure: The directory cannot be created.
  • Resolution: If the directory creation fails, there is a permission issue. Ask your server administrator to resolve it.

'cd' to the new directory

  • What's tested: This command tests if the new directory has proper permissions to allow us to change directory to it.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code).



    ftp>cd macr_test 250 CWD command successful.
  • Success: Current directory is changed.
  • Failure: You are unable to change to another directory.
  • Resolution: If this test fails, there is a permission issue. Ask you server administrator to resolve it. Improperly configured UNIX servers can have this problem, but it is rare.

Upload a file

  • What's tested: Upload the test file (explained above in setup instructions) to the server. This command checks to see if there are sufficient permissions to create a file on the server.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code).



    ftp>put test.htm 200 PORT command successful. 150 Opening ASCII mode data connection for test.htm. 226 Transfer complete. ftp: 83 bytes sent in 0.00Seconds 9000.00Kbytes/sec.
  • Success: File is uploaded.
  • Failure: The file can't upload.
  • Resolution: If this test fails, there is either a permission issue or a data transfer issue. However, since the directory listing test was already performed in the previous step, it probably is not a data transfer issue. Check with your server administrator to verify that you have permission to create files.

Rename the file

  • What's tested: This command tests to see if the server has basic rename functionality. When finished, rename the test file back to test.htm.



    Note:
    To function properly when rollbacks are turned on, it's necessary that Contribute can rename files.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code).



    ftp>rename test.htm test2.htm 350 File exists, ready for destination name 250 RNTO command successful.Now rename file back to "test.htm":



    ftp>rename test2.htm test.htm
  • Success: File is renamed.
  • Failure: You are unable to rename the file.
  • Resolution: If this test fails, it is most likely due to a file permission problem. Ask the server administrator to resolve it. Turn off the rollback feature in Contribute. If you still have problems, ask the server administrator to resolve the issue causing the rename to fail.

Move a file to a subdirectory

  • What's tested: The only way to move a file is by using the rename command. Some servers are OK performing a simple rename, but fail when trying to move files between directories. To perform this test, create a subdirectory in the macr_test directory and try renaming the file into that new folder. If it appears to work, 'cd' to the subdirectory and do a directory listing to be sure that it did in fact move.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code ).



    ftp>mkdir subdir 257 "subdir" directory created. ftp>rename test.htm subdir/test.htm 350 File exists, ready for destination name 250 RNTO command successful. ftp>cd subdir 250 CWD command successful. ftp>ls ordir 200 PORT command successful. 150 Opening ASCII mode data connection for /bin/ls. 09-11-04 02:20PM 83 test.htm 226 Transfer complete. ftp: 83 bytes received in 0.00Seconds 49000.00Kbytes/sec.
  • Success: A subdirectory is created, file is moved to that subdirectory, file shows in directory listing.
  • Failure: The subdirectory was not created, or the file was not moved to that subdirectory.
  • Resolution: If this test fails, the rollback feature breaks, and generates errors when publishing. Turn off rollbacks in Contribute. If you still have problems after disabling the rollback feature, ask the server administrator to resolve this rename/move issue.

Move a file to a parent directory

  • What's tested: After executing the previous step, the test file is in the "macr_test/subdir" directory. Move the file back to the macr_test directory using the rename command with the parameter "..". If it appears to work, 'cd ..' to go back up to macr_test and do a directory listing to make sure that it did in fact move. Some servers consider the ".." path component to be "illegal," which is not correct.



    Note:
    On Mac OS X, add a slash to the ".." parameter, for example, "../test.htm".
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code ).



    ftp>ls ordir drwxr-xr-x 4 user staff 136 Apr 14 11:30 . drwxr-xr-x 23 user staff 782 Apr 14 11:59 .. -rw-r--r-- 1 user staff 0 Apr 14 11:22 test.htm ftp>rename test.htm ../test.htm 350 File exists, ready for destination name 250 RNTO command successful. ftp>cd .. 250 CWD command successful. ftp>ls ordir drwxr-xr-x 4 user staff 136 Apr 14 11:30 . drwxr-xr-x 23 user staff 782 Apr 14 11:59 .. drwxr-xr-x 2 user staff 68 Apr 14 11:30 subdir -rwxrwxrwx 1 user staff 0 Apr 14 11:22 test.htm
  • Success: File is moved to the parent directory, file shows in the directory listing.
  • Failure: The file is not moved to the parent directory.
  • Resolution: If this process fails, the rollback feature breaks, which causes errors when publishing. Turn off rollbacks in Contribute. If you still have problems after disabling the rollback feature, ask the server administrator to resolve this rename/move issue.

Change permissions

  • What's tested: This test verifies that Contribute can change the permissions of a file, which occurs when rollbacks are enabled. First the permissions are displayed by listing the files. Then the permissions for the filetest.htm are changed to 777, which gives full permissions to all user. The original permissions for test.htm were -rw-r-r.



    Note: Permission parameters are r=read, w=write, x=execute, and the 3 represented users are current user/group/all.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code). Note: The chmod command used in this example is a literal command. It could be implemented differently on your server, if it does not work with the command below.



    ftp>ls ordir drwxr-xr-x 4 user staff 136 Apr 14 11:30 . drwxr-xr-x 23 user staff 782 Apr 14 11:59 .. drwxr-xr-x 2 user staff 68 Apr 14 11:30 subdir -rw-r--r-- 1 user staff 0 Apr 14 11:22 test.htm ftp>site chmod 777 test.htm Changing mode on /Users/user/macr_test/test.htm ftp>ls ordir drwxr-xr-x 4 user staff 136 Apr 14 11:30 . drwxr-xr-x 23 user staff 782 Apr 14 11:59 .. drwxr-xr-x 2 user staff 68 Apr 14 11:30 subdir -rwxrwxrwx 1 user staff 0 Apr 14 11:22 test.htm
  • Success: Permissions on the file have changed to what was set, or the server gives a "not implemented" error. If the server does not implement this command, it is possible that Contribute could still work, but it depends on the default server permissions. Talk to your server administrator if you have problems here.
  • Failure: Permissions are not changed, or the server returns an "access denied" or other similar error. Check with your administrator to make sure that you have the appropriate permissions. Also check to verify how to use chmod with your server.
  • Resolution: If the command fails with "NOT_IMPLEMENTED," Contribute could still be used with this server and there is no resolution needed. If this process fails with another error, check with administrator to make sure that user has the appropriate permissions.

Browse the test file via HTTP

  • What's tested: This command verifies that the file that was uploaded has permissions such that it can be viewed via the web server.
  • How to use: In a web browser, view the test file: http://theWebServer.com/macr_test/test.htm. This server name and path are just an example. Construct the appropriate URL based on the site root.
  • Success: The file can be viewed via a web browser.
  • Failure: The file cannot be viewed via a web browser.
  • Resolution: If you cannot view the file, there is either a permission problem, or the web server/FTP server root paths could be misconfigured. Ask the server administrator to modify the configuration and file permissions so that the file can be viewed via HTTP.



    Note: This test assumes that the HTTP server is up and running correctly and that other pages on the site are viewable as normal.

Logical FTP error tests

Contribute uses FTP in some specific methods to increase performance and information out of a server. These operations test the server to see if it behaves in a way that is compatible with Contribute. It's likely that these test uncover most server problems that you run into.

These logical tests require you to issue raw FTP commands to the server. The commands used in the steps above are "user friendly" commands. The command line client translatles them into the low-level FTP command and then sends them to the server. To issue a raw command to the FTP server, prepend your command with the "literal" keyword on Windows and "quote" on Mac OS X. For example, to execute a raw "change directory" command, type the following into the Command Prompt or Terminal. (The server response shows as code, and the portion you type appears as highlighted code.)

  • On Windows:ftp>literal CWD name_of_directory
  • On Mac OS X:ftp>quote CWD name_of_directory

The examples given below are all using the Windows "literal" keyword. If you are on the Mac, replace "literal" with "quote" for your commands.

Check for file existence (positive case)

  • What's tested: The FTP protocol does not have a command to check for existence. Contriute uses part of the rename command sequence to check for existence. Rename is actually two FTP commands, RNFR (ReNameFRom) followed by a second command RNTO (ReNameTO). The RNFR command checks for existence, then it ABOR (abort) the rename. On most FTP servers, RNFR returns 350 "file exists" or 550 "no such file". That error code is all that's checked to see if the file exists or not. However, some servers return odd error codes. Use the RNFR command, then ABOR the rename sequence to see if Contribute can get back a 350 on the test file.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code ).



    ftp>literal RNFR test.htm 350 File exists, ready for destination name ftp>literal ABOR 225 ABOR command successful.



    If the ABOR command fails, try finishing by renaming the file to its original name:



    ftp>literal RNTO test.htm 250 RNTO command successful.
  • Outcome: If the ABOR fails with a message of "no currently pending operation" or something similar, and the server is a UNIX server (case sensitive file system), issue an RNTO command to finish the rename. Contribute does this process if the ABOR fails for some reason. If this works, Contribute functions.



    If this check fails, you can work around this problem by turning off the "Use FTP optimizations" checkbox in the "Advanced..." section of the Connection wizard in Contribute versions 2.01 or later on Windows and version 3 on the Macintosh.

Check for file existence (negative case)

  • What's tested: Check for file existence on a file that does not exist. A "550 no such file" type of response is expected.
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code ).



    ftp>literal RNFR abcd1234 550 abcd1234: File does not exist.
  • Outcome: If this check fails, you can work around this problem by turning off Use FTP Optimizations. This setting is in the Advanced section of the Connection wizard in Contribute versions 2.01 or later on Windows and version 3 on the Mac OS.

Check for server state

  • What's tested: The rename command is two commands as mentioned above. This command forces the server to maintain an internal state (remembering the RNFR file while waiting for the RNTO name). In the existence check, you RNFR then ABOR. If the server does not properly maintain the rename state, this issue can sometimes leave the server in an unstable state.



    To test the server state, you perform an existence check on the test file, then attempt to download it. Errors that you can get in this case include:
    • An error code (450-553) with text indicating that "another operation is in progress" and the server refuses to execute that command, and sometimes refuses to execute all commands after getting into this state
    • Server crash
    • Failure downloading the file
    • Downloads the file, but the file locally is empty (zero bytes).
  • How to use: Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code ).



    ftp>literal RNFR test.htm 350 File exists, ready for destination name ftp>literal ABOR 225 ABOR command successful. ftp>get test.htm 200 PORT command successful. 150 Opening ASCII mode data connection for test.htm(83 bytes). 226 Transfer complete. ftp: 83 bytes received in 0.00Seconds 9000.00Kbytes/sec.
  • Success: The file is copied to your computer and the contents are correct (the same as in setup step 1 at the top).
  • Failure: The server fails to copy the file to your computer and generates an error message.
  • Resolution: If this check fails, however, it's likely Contribute won't work with this server at all. Server state checks are basic logic functionality. If Contribute can't determine if a server maintains state correctly, it can't function properly. The workaround is to find a new FTP server implementation.

Cleanup

Delete everything you created/uploaded. Delete the subdirectory, delete the test file, then change directories to the parent and delete the macr_test folder. Type the following into the Command Prompt or Terminal (server response shows as code, and the portion you type appears as highlighted code ).

ftp>rm subdir 250 RMD command successful. ftp>del test.htm 250 DELE command successful. ftp>cd .. 250 CWD command successful. ftp>rm macr_test 250 RMD command successful

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy