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

Minimum SFTP server access requirements

For Contribute to access a server, it's necessary that it can do the following:

  • Connect to the server and log in
  • Get a directory listing
  • Create directories
  • Change directory
  • Create files
  • Rename files
  • Change permissions (when using rollbacks)
  • Browse the test file

Setup

Windows

You use a test file to test the SFTP connection and the web server. Use a command line SFTP tool available from a third-party source. For example, PuTTY SFTP client (PSFTP) works well for this test.



Note: There are several PuTTY applications for download, but only PSFTP works for this test.

  1. Download and install the SFTP client software to the desktop.
  2. Create a test HTML file to upload during these tests:
    1. Copy and paste the following into a text file:

      <body > <p>This is a test file used during SFTP tests.</p> </body>
    2. Save the text file as "test.htm" on the desktop.
  3. Start Putty, "psftp.exe", from the desktop.

Mac OSX

You use a test file to test the SFTP connection and the web server. Mac OS X includes a command line SFTP tool that you can use for testing the connection.

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

      <body > <p>This is a test file used during SFTP tests.</p> </body>
    2. Save the text file as "test.htm" on the desktop.
  2. 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. This directory is often /Users/<user name>/. To determine that location within Terminal, run the command pwd (print working directory).
  4. Verify that the test file is in the current directory by doing the following:
    1. Type the list command, "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 the folder listed and repeat the ls command to verify the location.

Basic operational tests

These operations test the SFTP server for basic things like the ability to connect and transfer data, and 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 above.



Note: You could see slightly different results from the commands as the responses that the client SFTP software and the server generate. The following output is from the Macintosh Terminal.

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: sftp USER@<server>

    2: Connecting to <server>...

    3: user@<server>'s password:<password>

    4: sftp>



    The first time that you log in via SFTP, you see the public key returned along with a prompt to accept the key. For example:



    The authenticity of host 'your server (10.112.0.124)' can't be established. RSA key fingerprint is af:e7:4b:90:dc:5f:97:3c:ed:1f:21:7b:ff:73:e8:8e.

    Are you sure you want to continue connecting (yes/no)?
  • Success: User is prompted for password. If password is correct, sftp> 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 SFTP command line appears to freeze after the"dir" command, there could be a problem with establishing a data connection. Firewalls/proxies that block the incoming/outgoing data connection can 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).



    sftp>ls or (depending on server type) sftp>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 226 Transfer complete. sftp: 367 bytes received in 0.02Seconds 50.40Kbytes/sec.
  • Success: Files in directory are listed.
  • Failure: Window freezes.
  • Resolution: 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 new directory can be created, and provides a place to put the test files. Choose a directory name that does not yet exist.



    Note: Make sure that  Contribute can create directories to function.
  • 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).



    sftp>mkdir macr_test 257 "macr_test" directory created.
  • Success: Directory is created.
  • Failure: The directory cannot be created.
  • Resolution: If the directory creation fails, there is a permission issue that the server administrator must resolve.

'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).



    sftp>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 for the server administrator to resovle. 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 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).



    sftp>put test.htm 200 PORT command successful. 150 Opening ASCII mode data connection for test.htm. 226 Transfer complete. sftp: 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 step tests to see if the server has basic rename functionality. When finished, rename the test file back to "test.htm".



    Note:
     It's necessary that Contribute can rename files to function properly if rollbacks are turned on.
  • 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).



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



    sftp>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 for the server administrator to resolve. Turn off the rollback feature in Contribute. If you still have problems, the server administrator can 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).



    sftp>mkdir subdir 257 "subdir" directory created. sftp>rename test.htm subdir/test.htm 350 File exists, ready for destination name 250 RNTO command successful. sftp>cd subdir 250 CWD command successful. sftp>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. sftp: 83 bytes received in 0.00Seconds 49000.00Kbytes/sec.
  • Success: 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, which 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 the Macintosh, it's necessary to 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).



    sftp>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 sftp>rename test.htm ../test.htm 350 File exists, ready for destination name 250 RNTO command successful. sftp>cd .. 250 CWD command successful. sftp>ls or dir 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 test fails, the rollback feature breaks, which gives 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. This issue 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 users. 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).



    sftp>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 sftp>chmod 777 test.htm Changing mode on /Users/user/macr_test/test.htm sftp>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 that you have the appropriate permissions.
  • Resolution: If the command fails with"NOT_IMPLEMENTED," Contribute can still be used with this server and there is no resolution needed. If this test fails with another error, check with administrator to make sure that the user has the appropriate permissions.

Browse the test file via HTTP

  • What's tested: This test 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 your 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/SFTP server root paths could be misconfigured. Aks the server administrator  to modify the configuration or file permissions so that the file can be viewed via HTTP.



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

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).

sftp>rmdir subdir 250 RMD command successful. sftp>rm test.htm 250 DELE command successful. sftp>cd .. 250 CWD command successful. sftp>rmdir 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