Creating a Watch Folder with the Node API

Important: If you upgraded from Enterprise Server 3.6.1, Connect Server 3.6.1, Point-to-Point 3.6.1, or Desktop Client 3.6.1, and you had the asperawatchd and asperawatchfolderd services enabled and configured, you may have to make manually migrate your services depending on the user is running the services. For further details, see Migrating Watch Services on Upgrade.

A watch folder is an automation of file transfers from a source to a destination system. Files placed into a source folder are automatically transferred to the destination. It runs on the client side only and the recipient Aspera server endpoint does not need additional software components to support receiving data.

Process Overview:

Make sure the asperarund service is running.
Although asperarund starts automatically upon install, make sure the service is running, as watchfolder uses the service to start the asperawatchd and asperawatchfolderd watch services.
Configure the asperawatchd and asperawatchfolderd watch services.
Configure the Node API.
Create a watch folder using the aswatchfolderadmin utility.

Configuring Watchfolder Services

Watchfolders uses the Aspera Watchfolder service (asperawatchfolderd) and the output from the Aspera Watch Service (asperawatchd) to automatically transfer new files added to a source folder on an Aspera node. Follow the instructions below to start the two services.

Select a user account to run your services.

Watchfolder services must be run under a user with access to every area of your file system in which you intend to create a watch folder. Watchfolders allows you to run multiple instances of these services under different users. Most users run these services under one user. Choose a user that has access to your entire file system.

If you need to run multiple instances of these services to access every area of your file system, see Choosing User Accounts to Run Watchfolder Services.
Configure a docroot for the chosen user.
The docroot is a security feature that allows you to restrict the area of the file system that a user, and services run by that user such as the Aspera Watch Service, can access. If a user needs access to the entire file system, set the docroot path as /, but you cannot leave it empty.
Set the user's docroot by running the following command:
```
# asconfigurator -x "set_user_data;user_name,username;absolute,docroot"
```
For example:
```
# asconfigurator -x "set_user_data;user_name,root;absolute,/"
success
user_name: root
```
Ensure the user has permissions to write to the default log directory if no directory is specified.
For more information about configuring log directories, see Watch Service Configuration.
Configure the asperawatchd and asperawatchfolderd services to run under your user.
The following commands add the services in the asperarund database; asperarund automatically starts and preserves services in its database. The asperarund service must be running.
```
# /opt/aspera/sbin/asperawatchd --user username
# /opt/aspera/sbin/asperawatchfolderd --user username
```
Verify that asperawatchd and asperawatchfolderd is running under the given user.
Use the aswatchadmin and aswatchfolderadmin admin tools to retrieve a list of running daemons. Daemons are named with the username you passed in when starting the service. For example, if you used the root user to run your services, you should see the root daemon listed when you run the following commands:
```
# /opt/aspera/bin/aswatchadmin query-daemons
[aswatchadmin query-daemons] Found a single daemon:
	root

# /opt/aspera/bin/aswatchfolderadmin query-daemons
[aswatchfolderadmin query-daemons] Found a single daemon:
	root
```

Configuring the Node API

Create a Node API user and map it to a system account. The user account must have administrative (root / sudo) privileges to interact with asperawatchfolderd.
```
# /opt/aspera/bin/asnodeadmin -a -u node_username -p node_password -x admin_user --acl-set "admin,impersonation"
```
For example:
```
# /opt/aspera/bin/asnodeadmin -a -u watchfolder_user -p X245lskd3 -x root --acl-set "admin,impersonation"
```
Adding, modifying, or deleting a node-user triggers automatic reloading of the user database and the node's configuration and license files. For more information on the Node API, see your transfer server's administrator guide.

Verify that you correctly added the node user.

# /opt/aspera/bin/asnodeadmin -l
List of node user(s):
                user       system/transfer user                    acls
====================    =======================    ====================
       node_api_user                system_user    [admin]

Given the example in the previous step, the output should look like the following:

# /opt/aspera/bin/asnodeadmin -l
                user       system/transfer user                    acls
====================    =======================    ====================
watchfolder_user                          root    [admin,impersonation]

Creating a Watch Folder with the Node API

The instructions below uses curl commands to create watch folders.

Retrieve a list of running asperawatchfolder daemons. Daemons are named with the username passed in when starting the service.
Run the following aswatchfolderadmin command:
```
# /opt/aspera/bin/aswatchfolderadmin query-daemons
[aswatchfolderadmin query-daemons] Found a single daemon:
	root
```

Create and configure a JSON configuration file for each watch folder.

You must configure the following fields for a valid JSON configuration for a watch folder:

Field	Description
id (optional)	A unique ID for the watchfolder. If this field is not configured, a uuid is automatically generated for the watchfolder.
source_dir	The source directory, relative to the user's docroot. When `asperawatchd` detects a new file in this location, `asperawatchfolderd` starts an ascp session to transfer the file to target directory. This directory must be within the docroot set for the user running asperawatchd.
target_dir	The target directory, relative to the user's docroot. If this is a remote directory, define the remote machine in the host field and provide SSH crednetials for the remote machine in the user and pass fields.
host	The host of the target directory. The host can be specified with an IPv4 or IPv6 address. The preferred format for IPv6 addresses is x:x:x:x:x:x:x:x, where each of the eight x is a hexadecimal number of up to 4 hex digits. Zone IDs (for example, %eth0) can be appended to the IPv6 address.
user	The username for the host of the target directory.
pass	The password for the host of the target directory.

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

For example:

{
    "source_dir": "/src",
    "target_dir": "/dest",
    "transport": {
        "host": "198.51.100.22",
        "user": "watchfolder_admin",
        "pass": "XF324cd28"
    }
}

For a full reference to the options you can configure, see Configuring the Watch Folder JSON Configuration File.

Save the configuration file.

Verify that a Node API user has been configured correctly for the system user running the asperawatchd and asperawatchfolderd services.

# /opt/aspera/bin/asnodeadmin -l 
List of node user(s):
                user       system/transfer user                    acls
====================    =======================    ====================
       node_api_user                system_user    [admin]

Use the Node API start a watch folder instance with the JSON configuration file.

Pass the configuration file into a curl command to start a watch folder with the Node API:

# cat path/to/json_file | curl -k --user node_api_user:node_api_password -X POST -d @- https://host:node_api_port/v3/watchfolders

Tip: By default, the Node API port is 9092.

For example:

# cat ~/watchfolder_conf.json | curl -k --user watchfolder_admin:XF324cd28 -X POST -d @- https://198.51.100.22:9092/v3/watchfolders
{
"id": "b394d0ee-1cda-4f0d-b785-efdc6496c585"
}

Verify the watch folder is running.
Retrieve the status of the new watch folder using the following curl command:
```
# curl -k --user node_api_user:node_api_password https://host:node_api_port/v3/watchfolders/watchfolder_id/state
```
For example:
```
# curl -sk --user watchfolder_admin:XF324cd28 https://198.51.100.22:9092/v3/watchfolders/b394d0ee-1cda-4f0d-b785-efdc6496c585/state
```
Make sure the state of the watch folder in the resulting out put is "state":"HEALTHY".
Test your watch folder.
Add files to the source directory you configured in the JSON configuration file. If the configuration is correct, Watchfolder detects the new files, starts a transfer, and the added files appear in the target directory.

After creating your watch folder, you can manage the watch folder using the Node API. For more information, see Managing Watch Folders with the Node API.

Parent topic: Working With Aspera Watchfolders