Starting Aspera Watch Services and Creating Watches

The Aspera Watch Service (asperawatchd) is a file system change detection and snapshot service that is optimized for speed, scale, and distributed sources. On file systems that have file system notifications, changes in source file systems (new files and directories, deleted items, and renames) are detected immediately, eliminating the need to scan the file system. On file systems without file notifications, such as object storage, Solaris, AIX, and Isilon, file system scans are automatically triggered.

The Aspera Watch Service can be used on any local or shared (CIFS, NFS) host. However, when watching mounted shared storage and the change originates from a remote server, the Watch Service does not receive file notifications. In such cases, set <scan_period> in aspera.conf to frequent scans, such as 1 minute. See the following steps for instructions.

When used in conjunction with ascp commands, the Aspera Watch Service enables fast detection and transfer of new and deleted items. For more information on using watches with ascp, see Transferring and Deleting Files with the Aspera Watch Service.

To start the Aspera Watch Service and subscribe to (create) a watch:

Configure a docroot or restriction for the user.

Docroots and path restrictions limit the area of a file system or object storage to which the user has access. Users can create Watch Folders and Watch services on files or objects only within their docroot or restriction.

Note: Users can have a docroot or restriction, but not both or Watch Folder creation fails.

Docroots can be set up in the GUI or command line. In the GUI, click Configuration > Users > username > Docroot and set the permitted path as the value for Absolute Path. To set up a docroot from the command line, run the following command:

# asconfigurator -x "set_user_data;user_name,username;absolute,docroot"

Restrictions must be set from the command line:

# asconfigurator -x "set_user_data;user_name,username;file_restriction,|path"

The restriction path format depends on the type of storage. In the following examples, the restriction allows access to the entire storage; specify a bucket or path to limit access.

Storage Type	Format Example
local storage	For Unix-like OS: specific folder: file:////`folder`/* drive root: file:////* For Windows OS: specific folder: file:///c%3A/`folder`/* drive root: file:///c*
Amazon S3 and IBM Cloud Object Storage - S3	s3://*
Azure	azu://*
Azure Files	azure-files://*
Azure Data Lake Storage	adl://*
Alibaba Cloud	oss://*
Google Cloud	gs://*
HDFS	hdfs://*

With a docroot or restriction set up, the user is now an Aspera transfer user. Restart asperanoded to activate your change:

Run the following commands to restart asperanoded:

# systemctl restart asperanoded

or for Linux systems that use init.d:

# service asperanoded restart

Ensure the user has permissions to write to the default log directory if no directory is specified.
For more information about configuring log directories, seeWatch Service Configuration.
Configure Watch Service settings.
Though the default values are already optimized for most users, you can also configure the snapshot database, snapshot frequency, and logging. For instructions, see Watch Service Configuration.
Start a Watch Service under the user.
The following command adds the Watch Service run under the user to the Aspera Run Service database:
```
# /opt/aspera/sbin/asperawatchd --user username [options]
```
Verify that the Watch Service daemon is running under the user.
Use the aswatchadmin utility to retrieve a list of running daemons. Daemons are named for the user who runs the service. For example, if you started a Watch Service under root, you should see the root daemon listed when you run the following command:
```
# /opt/aspera/bin/aswatchadmin query-daemons
[aswatchadmin query-daemons] Found a single daemon:
	root
```
Create a watch.
A watch is a path that is watched by the Aspera Watch Service. To create a watch, users subscribe to a Watch Service and specify the path to watch. run the following command, where daemon is the username used to start the asperawatchd service and filepath is the directory to watch:
```
# /opt/aspera/bin/aswatchadmin subscribe daemon filepath
```
When you create a new subscription, you can also set watch-specific logging, database, scan period, and expiration period, and override aspera.conf settings.

Note: The default scan period is 30 minutes. If you are watching a file system that does not support file system notifications (such as object storage, mounted storage (NFS), Solaris, AIX, and Isilon), Aspera recommends setting a more frequent scan to detect file system changes quicker.

For more information on using these options, see Managing Watch Subscriptions or run:
```
# /opt/aspera/bin/aswatchadmin subscribe -h
```
Note: The default expiration for watches is 24 hours. If a watch subscription expires before the user resubscribes to it, a new subscription must be created.