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

The /v3/watchfolders endpoint has 2 versions. This article describes creating a Push Watch Folder with version 2017_09_14, which supports authentication to the remote server only by using SSH credentials. To authenticate with Node API credentials, an access key ID and secret, or IBM Aspera Shares credentials, use the 2017_10_23 version.

Prerequisites

  • You must have Node API credentials for the local server.
  • You must have SSH credentials for the remote server.

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.
  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. For Watch Folders sources that are version 3.8.0 and newer, you can start services through the API or command line on the local server. The following sub-steps describe how to start services with the API; see the next step for command line instructions.
    1. Create a JSON configuration file for the 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"
      
    4. 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.

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

    6. Confirm that the service is running.
      # curl -ki -u node_username:node_password -X GET "https://localhost:9092/rund/services/service_id"
      
  3. For Watch Folders sources that are version 3.7.4 and older, start services by running the following commands (these are for Linux):
    # /opt/aspera/sbin/asperawatchd --user username
    # /opt/aspera/sbin/asperawatchfolderd --user username
    

    Verify that the services are running for the user by running the following command:

    # /opt/aspera/bin/asrun send -l
    
  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 push Watch Folder configuration has the following syntax:

    {
        "source_dir": "source_directory",
        "target_dir": "target_directory",
        "transport": {
            "host": "ip_address",
            "user": "username",
            "pass": "password"
        }
    }
     
    

    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 -X POST -d @path/to/json_file https://host:node_api_port/v3/watchfolders
    

    By default, the API port is 9092.

    For example:

    # curl -k --user watchfolder_admin:XF324cd28 -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 -X GET https://host:node_api_port/v3/watchfolders/watchfolder_id/state
    

    For example:

    # curl -sk --user watchfolder_admin:XF324cd28 -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".