Accessibility

TechNote (Archived)

Testing FTP functions using command line

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

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

Minimum FTP server access requirements

In order for Contribute to access a server, Contribute must be able to do the following:

Setup

You will need to use a command line FTP tool. Both Macintosh OSX and the Windows operating systems come with a command line FTP tool. Additionally a test file will be used 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. This is done differently depending on whether you use a Macintosh or Windows platform.
    • Windows platforms:
      1. Click the Windows Start button, then choose Run.
      2. Type cmd in the Run dialog box.
      3. Click OK. This is the Command Prompt window, which you use to communicate with the MS-DOS operating system. This may also be called the DOS prompt.
    • Macintosh OSX:
      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 DOS prompt line in the Command Prompt window indicates the home directory. This directory is usually C:\Documents and Settings\<username>.
    • Mac OSX: Within Terminal, run pwd (print working directory). This directory is usually Users/<username>.
  4. Verify that the test file is in the current directory.
    • Windows platforms:
      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.
    • Macintosh OSX:
      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 just test to see if the "lamp with the burned out light bulb is plugged in." These commands should be typed in the command line tool as mentioned in step 2 above.

Connect to the server and log in
  • What this tests: This tests if the server is live and reachable, and if the username/password is correct.
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted code ). Line numbers are provided only for reference and will not be 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 username (you do not see line 3), investigate your login information (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 this tests: This 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. This failure can be caused by not having the appropriate passive vs. non-passive mode set in the FTP client. It can also be caused by firewalls/proxies that block the incoming/outgoing data connection.
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted 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 may be blocking connections. Resolve any data transfer problems before proceeding.
Create a new directory
  • What this tests: This tests if a new directory can be created, and provides a place to put the test files. Choose a directory name that does not yet exist.

    Note: Contribute needs to be able to create directories to function.
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted 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 that will need to be resolved by the server administrator.
'cd' to the new directory
  • What this tests: This 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 will show ascode, and the portion you type appears ashighlighted 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 fails, there is a permission issue that will need to be resolved by the server administrator. Improperly configured UNIX servers may have this problem, but it is extremely rare.
Upload a file
  • What this tests: Upload the test file (explained above in setup instructions) to the server. This will check to see if there are sufficient permissions to create a new file on the server.
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted 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 will not upload.
  • Resolution: If this 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 this tests: This tests to see if the server has basic rename functionality. When finished, rename the test file back to "test.htm".

    Note:     Contribute needs to be able to rename files to function properly if rollbacks are turned on.
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted 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 fails, it is most likely due to a file permission problem that the server administrator will need to resolve. Turn off the rollback feature in Contribute. If you still have problems, the server administrator will need to resolve the issue causing the rename to fail.
Move a file to a subdirectory
  • What this tests: 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 new 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 will show ascode, and the portion you type appears ashighlighted 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: New 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 fails, the rollback feature will break, which will generate errors when publishing. Turn off rollbacks in Contribute. If you still have problems after disabling the rollback feature, the server administrator will need to resolve this rename/move issue.
Move a file to a parent directory
  • What this tests: After executing the previous step, the test file will be 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 the Macintosh, you must add a slash to the ".." parameter, for example, "../test.htm".
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted 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 fails, the rollback feature will break, which will give errors when publishing. Turn off rollbacks in Contribute. If you still have problems after disabling the rollback feature, the server administrator will need to resolve this rename/move issue.
Change Permissions
  • What this tests: This test verifies that Contribute can change the permissions of a file. This would occur 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 followinginto the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted code).Note: The chmod command used in this exampleis aliteral command and may be implemented in a different way 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 might 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 you have the appropriate permissions. Also check toverify how to use chmod with your server.
  • Resolution: If the command fails with "NOT_IMPLEMENTED," Contribute may still be used with this server and there is no resolution needed. If this fails with another error, check with administrator to make sure user has the appropriate permissions.
Browse the test file via HTTP
  • What this tests: This 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. You will need to 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 may be misconfigured. The server administrator will need to modify the configuration and/or file permissions so that the file can be viewed via HTTP.

    Note: This assumes that the HTTP server is up and running correctly. Other pages on the site should be 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. Most server problems that you run into will probably be uncovered by these tests.

These logical tests will require you to issue raw FTP commands to the server. The commands used in the steps above are "user friendly" commands that are translated by the command line client into the low level FTP command and then sent to the server. To issue a raw command to the FTP server, you will need to prepend your command with the "literal" key word 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 (server response will show 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, just replace "literal" with "quote" for your commands.

Check for file existence (positive case)
  • What this tests: The FTP protocol does not have a command to check for existence. We use 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). We use the RNFR command to check for existence, then we ABOR (abort) the rename. On most FTP servers, RNFR returns 350 "file exists" or 550 "no such file". That error code is all we check 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 we can get back a 350 on our test file.
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted 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 if the ABOR fails for some reason. If this works, Contribute will function.

    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 this tests: Check for file existence on a file that does not exist. We expect to get a "550 no such file" type of response.
  • How to use: Type the following into the Command Prompt or Terminal (server response will show ascode, and the portion you type appears ashighlighted 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 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 server state
  • What this tests: The rename command is two commands as mentioned above. This 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 can sometimes leave the server in an unstable state.

    To test this, you will perform an existence check on the test file, then attempt to download it. Errors that you may get in this case include:
    • An error code (450-553) with text indicating that "another operation is in progress" and the server will refuse to execute that command, and sometimes will refuse 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 will show ascode, and the portion you type appears ashighlighted 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, Contribute will most likely not 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 will be unable to 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 will show 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

AlertThis content requires Flash

To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player.

Download the free Flash Player now!

Get Adobe Flash Player

Creative Commons License

Search Support


Document Details

ID:tn_19496
Browser:Chrome
Internet Explorer
Netscape
Opera
Safari
Firefox

Products Affected:

contribute