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_10_23, which supports authentication to the remote server by using SSH credentials, Node API credentials, an access key ID and secret, or IBM Aspera Shares credentials.

Prerequisites

  • You must have Node API credentials for the local server.
  • You must have SSH credentials, 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.
  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 service on the local server.
    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"
      
  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 push Watch Folder configuration has the following syntax:

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

    For example, to push to your AWS S3 storage through the IBM Aspera on Cloud transfer service, the configuration is similar to the following:

    {
        "source": {
            "path": "/projects/projectA/images",
         },
         "target": {
            "path": "/images",
            "location": {
                "type": "REMOTE",
                "host": "https://ats-aws-sa-east-1.aspera.io",
                "port": 443,
                "authentication": {
                     "type": "NODE_BASIC",
                     "user": "diDeuFLcpG9IYdsvxj0SCq4mOohNJTKvp5Q2nRWjDgIA",
                     "pass": "ZGlEZXVGTGNwRzlJWWRzdnhqMFNDcTRtT29oTkp"
                }
            }
         },
         "watchd": {
            "scan_period": "30m"
         }
    }

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