What is the ColorNet Directory Watch Utility?
ColorNet Directory Watch is a standalone utility for executing a command when a file within a specified directory is created, modified and/or deleted.
Although there are various use cases for such a utility, one of the most common may be for processing an incoming document or file feed. In this use case, every time a new document or file is deposited into a particular "feed" directory, a program is kicked off to process that document or file.
Another common use case is when files within a directory are cached -- in memory and/or an application -- such that a utility like Directory Watch can signal when the cache needs to be updated because one or more files in the underlying directory have been modified.
What are the Advantages of Using ColorNet Directory Watch
Although some operating systems may provide a few different ways to launch a command when a directory changes, the ColorNet Directory Watch utility has a number of conveniences, including:
o Option to wait until the file is closed before running the command (1)
-wait option prevents a file from being processed while it is still being created or transferred
o Option to process subdirectories
-recursive option includes all subdirectories, including newly created ones
o Options to filter files using regular expressions patterns
-exclude will ignore matching files and -include will only process matching files
o Option to run in the background
-pipe {named-pipe} will receive additional input commands from a named pipe (2)
o Option to log the output of each command / job executed
-log {directory} will create a log file for each command run, with the full command, stdout & stderr
o Option to only include certain types of directory events
-event runs command only when files are created, deleted or modified or any (default)
The -command option specifies the command to run, and is specified as:
-command {command-line}
where {command-line} may include the parameters:
| {EVENT} |
- which is substituted with the type of event (e.g. ENTRY_CREATE) |
| {FILENAME} |
- which is substituted with the name of the file affected |
| {FULLPATH} |
- which is substituted with the full path of the file affected |
The possible {EVENT} values are:
ENTRY_CREATE - a new file was created in the directory
ENTRY_DELETE - a file was deleted from the directory
ENTRY_MODIFY - a file was modified in the directory
What are the Requirements & Limitations?
The ColorNet Directory Watch utility requires Java 8+.
Support for filesystem notifications can very by operating system and Java Runtime (JRE) implementation, and while many platforms are fully supported (e.g., Linux), some platform implementations may utilize polling, which is slower and may miss some events (such as creating and deleting the same file within the polling interval).
(1) The -wait option requires the lsof command, which is available for macOS, Linux, and most Unix-based operating systems, but may not be available for all platforms.
(2) The -pipe option uses a named pipe for reading commands, which is available for macOS, Linux, and most Unix-based operating systems, but may not be available for all platforms.
How Do I Run ColorNet Directory Watch from the CLI (Command Line Interface)?
- Download the Directory Watch utility (either tar or zip)
- Unpack the Archive:
$ tar xvf DirectoryWatch-1.0.0.tar
or
$ unzip DirectoryWatch-1.0.0.zip
- Run the Directory Watch utility:
$ cd DirectoryWatch-1.0.0
$ ./DirectoryWatch run "{options}"
Note: If you specify more than one option, you must enclose them in quotes
How Do I Install ColorNet Directory Watch as a Service?
NOTE: You must edit the file options.txt to include two lines before installing as a service (see sample provided):
options={list of options to use}
command={command to run}
To install Directory Watch as a service in:
MacOS (using launchctl): /Library/DirectoryWatch
Linux (using systemd): /opt/DirectoryWatch
- Download Directory Watch (either tar or zip)
- Unpack the Archive
$ tar xvf DirectoryWatch-1.0.0.tar
or
$ unzip DirectoryWatch-1.0.0.zip
- Customize Directory Watch for your own use (if not using the example service provided)
$ cd DirectoryWatch-1.0.0
$ vi options.txt <== Add the desired options from above
- Install Directory Watch as a Service:
$ ./DirectoryWatch install
How Do I Manage the Directory Watch Service?
From the service directory:
MacOS: /Library/DirectoryWatch
Linux: /opt/DirectoryWatch
To stop the service:
$ ./DirectoryWatch stop
To start the service:
$ ./DirectoryWatch start
To display the service status:
$ ./DirectoryWatch status
To uninstall the service:
$ ./DirectoryWatch uninstall
Can I Send Interactive Commands to Directory Watch?
[Experimental Feature]
You may send Directory Watch a command, by specifying either the -interactive (receives commands from stdin) or -pipe (receives commands from a named pipe) options. The following commands are currently supported (always end a command with a semi-colon (';')):
exit;
- Exit Directory Watch
show directories;
- Show all directories currently being watched, e.g.
watch> show directories;
Directories Watched:
/tmp
show files;
- Show all file events that have occurred
- Displays each event {date} {time} {event} {filename}, e.g.
watch> show files;
File Events:
Mon Jun 12 17:51:33 EDT 2023 ENTRY_CREATE /tmp/goodbye.txt
Mon Jun 12 17:51:13 EDT 2023 ENTRY_CREATE /tmp/hello.txt
show job {id};
- Shows the details of a particular job
- Displays job details, stdout, stderr, and exit value, e.g.
watch> show job 8c8245c8c3614c169cd9cc15eb5d6ffc;
Job ID : 8c8245c8c3614c169cd9cc15eb5d6ffc
Job Status : finished
Job Start : Mon Jun 12 17:51:13 EDT 2023
Job End : Mon Jun 12 17:51:13 EDT 2023
Job Wait : false
Command Run : sample.sh ENTRY_CREATE /tmp/hello.txt hello.txt
File Path : /tmp/hello.txt
File Event : ENTRY_CREATE
Exit Value : 0
Standard Out :
show jobs;
- Show all jobs (commands) submitted (reverse chrono)
- Displays job {id} {event} {fullpath} {filename}, e.g.
watch> show jobs;
Jobs Submitted:
Job: eb6abe3988c243a898f7ee554fcd72a4 File: /tmp/goodbye.txt
=> sample.sh ENTRY_CREATE /tmp/goodbye.txt goodbye.txt
Job: 8c8245c8c3614c169cd9cc15eb5d6ffc File: /tmp/hello.txt
=> sample.sh ENTRY_CREATE /tmp/hello.txt hello.txt
quit;
- Same as exit;
What Example Service is Provided?
The downloaded Directory Watch service includes the following options.txt:
options=-directory /tmp -event create -include .*\.txt
command=sample.sh {EVENT} {FULLPATH} {FILENAME}
This will monitor the /tmp directory for any new text (*.txt) files that have been created. If a new text file is detected, it will run the example bash script provided (sample.sh), passing it the file event (ENTRY_CREATE), the full path of the new text text file, and also just the filename of the new text file.
The example bash script (sample.sh) will send an e-mail message similar to the following if a text file (e.g., hello.txt) is created in /tmp:
From: jsmith@some.server.com (John E. Smith)
Subject: hello.txt
Date: June 12, 2023 at 5:51:13 PM EDT
To: someone@somedomain.com
ENTRY_CREATE /tmp/hello.txt
The example bash script (sample.sh) should be edited so that SENDTO defines a valid e-mail address. It also assumes that the mailx command has been installed and properly configiured to send e-mail to the SENDTO address.
Please edit the file options.txt to include the desired options and command to be executed for your own use. This will require stopping and then re-starting the Directory Watch service for any changes to take affect.
Still To Do
The following are Directory Watch features that are not currently supported, but may be added in the future:
o Different commands for different directories
o Different commands for different file names or types
o Scheduled commands
