Pull Watch Folders automatically transfer new and modified files and directories from the remote server to the local server (where the local server is the one to which you send the Watch Folders API request).

Prerequisites

  • You must have Node API credentials for the local server.
  • You must have an access key ID and secret, a Node API credentials, or IBM Aspera Shares credentials for the remote server. If you use Node API credentials, the transfer user must be configured with a docroot rather than a file restriction.
  • Both the local and remote servers must be running HST Server or HST Endpoint version 3.8.0 or newer.

Restrictions on all Watch Folders

  • Only local-to-remote (push) and remote-to-local (pull) configurations are supported. Remote-to-remote and local-to-local are not supported.
  • Growing files are only supported for local sources (push Watch Folders) and must be authenticated by a transfer user (password or SSH key file). The transfer user cannot be restricted to aspshell and the source cannot be in object storage.
  • Source file archiving is not supported if the Watch Folder source is in object storage.
  • IBM Aspera Shares endpoints must have version Shares version 1.9.11 with the Watch Folder patch or a later version.

Restrictions on Pull Watch Folders

  • Pull Watch Folders must be authenticated with an access key ID and secret, a Node API username and password, or IBM Aspera Shares credentials. SSH authentication is not supported for remote sources.
  • Pull Watch Folders that use Node API authentication cannot be authenticated with a Node API user whose associated transfer user is configured with a restriction (the Watch Folder status is reported as impaired). Edit the transfer user’s configuration to use a docroot, restart asperanoded, and the Watch Folder recovers automatically.
  • Pull Watch Folders cannot use IBM Aspera on Cloud (including IBM Aspera on Cloud transfer service nodes) or IBM Aspera Transfer Cluster Manager nodes as the remote source.
  • Pull Watch Folders do not support growing files.
  1. Ensure that the Aspera Run service (asperarund) is running.

    On Linux servers, run the following command:

    service asperarund status
    Aspera Run Server: asperarund           [ RUNNING ]
    
  2. Create a Watch Service on the remote server.

    This approach requires that you have node credentials for the remote server.

    1. Create a JSON configuration file for the remote Watch Service.
      {
          "type": "WATCHD",
          "run_as": {
              "user": "username",
              "pass": "password"
          },
          "enabled": true
      } 
      

      The username and password are for a transfer user with permissions to the source path. Save the file as wfd_create.json.

    2. To create the service, run the following command:
      # curl -ki -u node_username:node_password -X POST -d @wfd_create.json "https://server_ip_address:9092/rund/services"
      

      The output includes the service ID. Record the ID for the next substep.

    3. Confirm that the service is running.
      # curl -ki -u node_username:node_password -X GET "https://server_ip_address:9092/rund/services/service_id"
      
  3. Create the Watch Folder service on the local computer.
    1. Create a JSON configuration file for the service with the following text:
      {
          "type": "WATCHFOLDERD",
          "run_as": {
              "user": "username",
              "pass": "password"
          },
          "enabled": true
      } 
      

      The username and password are for a transfer user with permissions to the source path. Save the files, with the .json extension.

    2. Create the service.
      # curl -ki -u node_username:node_password -X POST -d @config_file "https://localhost:9092/rund/services"
      

      If service creation succeeds, the ID of the service is returned. Record the ID for use in the next step.

    3. Confirm that the service is running.
      # curl -ki -u node_username:node_password -X GET "https://localhost:9092/rund/services/service_id"
      
  4. Create a JSON configuration file for your Watch Folder.

    The Watch Folder JSON file describes the source, target, and authentication to the remote server, and can also specify transfer session settings, file handling and post-processing, filters, and growing file handling.

    A basic pull Watch Folder configuration has the following syntax:

    {
        "source": {
            "path": "source_directory",
            "location": {
                "type": "REMOTE",
                "host": "ip_address",
                "port": port,
                "authentication": {
                    "type": "NODE_BASIC",
                    "user": "username",
                    "pass": "password"
                 }
            }
        },
        "target": {
            "path": "target_directory"
        },
        "watchd": {
            "scan_period": "scan_period",
            "identifier": "daemon"
        }
    }
    

    For a full configuration reference, see the IBM Aspera High-Speed Transfer Server Admin Guide and the endpoint reference in IBM API Explorer.

    Save the configuration file. The path to the configuration file is used in the next step.

  5. Start the Watch Folder.
    # curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X POST -d @path/to/json_file https://host:node_api_port/v3/watchfolders
    

    By default, the API port is 9092.

    Note: The header "X-aspera-WF-version:2017_10_23" is required when submitting POST, PUT, and GET requests to /v3/watchfolders on servers that are version 3.8.0 or newer. This enables Watch Folders to parse the JSON “source” and “target” objects in the format that was introduced in version 3.8.0.

    For example:

    # curl -k --user watchfolder_admin:XF324cd28 -H "X-aspera-WF-version:2017_10_23" -X POST -d @/watchfolder_conf.json https://198.51.100.22:9092/v3/watchfolders
    {
    "id": "b394d0ee-1cda-4f0d-b785-efdc6496c585"
    }
    
  6. Verify that the Watch Folder is running.
    # curl -k --user node_api_user:node_api_password -H "X-aspera-WF-version:2017_10_23" -X GET https://host:node_api_port/v3/watchfolders/watchfolder_id/state
    

    For example:

    # curl -sk --user watchfolder_admin:XF324cd28  -H "X-aspera-WF-version:2017_10_23" -X GET https://198.51.100.22:9092/v3/watchfolders/b394d0ee-1cda-4f0d-b785-efdc6496c585/state
    

    If the Watch Folder is running, it is reported with "state":"HEALTHY".