MyTrigger documentation

What is MyTrigger?
What kind of events are detected?

Changes in a file system folder.
When something is written in the Event log.
When processes starts/stops, becomes unresponsive or runs amok.
When services starts/stops.
Changing active WLAN access point.
Inserting/removing USB devices.

What kind of programs can be started?
What about security?
How do I Install MyTrigger?
Using MyTrigger

Creating a WLAN trigger.
Creating a USB trigger.
Creating a process trigger.
Creating a folder trigger.
Creating an Event log trigger.
Creating a service trigger.

Advanced usage

Regular Expressions
Passing parameters
The settings files
Signing the settings files
Hiding the tray icon
Closing running instances

Running MyTrigger as a service
The log file

Feedback and reporting errors

1. What is MyTrigger?

MyTrigger is a small program that can launch arbitrary programs when specific system events occur on your computer. You tell MyTrigger what system events to watch by creating triggers that defines what event to listen for and what action to take when the events occurs. MyTrigger lets you detect changes in the file system, when something is written in the system event log, when a service starts or stops and many other things.

MyTrigger can optionally be run as a system service. That means that MyTrigger will start when the computer starts and will run as long as the computer is running. There's no need for a user to log on to the computer. This is useful if you want to use MyTrigger to monitor events on a server computer where typcally no user will be logged on.

2. What kinds of events are detected?

2.1 Changes in a file system folder MyTrigger can be set to monitor a folder on your hard disk. Monitoring a folder, MyTrigger can react on any combination of adding a file/folder, removing a file/foler, renaming a file/folder, modifying the contents of a file or modifying the "meta data" about a file or folder. The meta data includes security descriptors, file attributes, last access time etc. This feature turns MyTrigger into an effective file system monitor, you can use it to script important actions when a file is received by FTP or similar.

2.2 When something is written in the Event log MyTrigger can watch the Event log for you. Many applications and subsystems report various things in one of the three default event logs. With MyTrigger you can monitor these logs and take suitable action whenever something interesting is written for every single entry or only for entries that matches your filter. You can send over 10 different parameters describing the written entry to the the program or script you specify.

2.3 When processes starts/stops, becomes unresponsive or runs amok. MyTrigger can also be used to detect when another program starts or exits, becomes unresponsive or runs amok. There are numerous of situations where this is useful. You could for instance create a script that shuts down your VPN client as soon as you close your email program to minimize the time that your computer has access to a protected network. You can turn MyTrigger into a server watchdog that tracks the processes on your servers so that you can react immediately if an important process dies or suddenly uses all available CPU.

2.4 When services starts/stops. With MyTrigger you can monitor the various services installed on your computer. This is similar to monitoring a specific process. But since a service can be implemented in so many other ways than just a single exe, this feature enables you to specifically trace when services starts or stops.

2.5 Changing active WLAN access point If you are a WLAN user, you can user MyTrigger to change your computers configuration when your computer enters or leaves your office or home WLAN network. For instance, you could make sure that any open file shares are closed as soon as your computer is moved outside your office. Or you could run a program that looks for Virus definition updates as soon as the laptop gets back in to the office.

2.6 Inserting/removing USB devices The USB device trigger can be used for a wide range of automation tasks. MyTrigger can be configured to recognize when you connect you digital camera and move all pictures on the camera to the hard drive. Or you could create a very simple access control system that identifies users based on the USB key ring memory they insert into a running computer.

3. What kind of programs can be started?

The programs you configure MyTrigger to run are specified pretty much the same way as you would start a program via the Windows Run command. If you want to start the built in calculator, you could simply tell MyTrigger to start "calc.exe" for a specific event. A Perl script would be started with the command "Perl myscript.pl" and a VB-Script with "CScript myvbscript.vbs" or just myvcscript.vbs if either CScript or WScript is associated with the .vbs file extention (as it is by default). If you can start the program via the Run command or a command shell, you can configure MyTrigger to start it.

MyTrigger can also start a Windows Scheduled Task. To start a Scheduled Task with the name "CopyLogfile", you would instruct MyTrigger to start the program "CopyLogFile.job". The thing to remember is that Scheduled Tasks are stored on you computer as .job files in a specific Windows folder, that's why MyTrigger uses the .job extension to distinguish Scheduled Tasks from other types of programs you would want to start. When MyTrigger starts a Scheduled Task, it's the same thing as when you open the Scheduled Tasks Folder, right click on a task and select "Run". The abillity to start a Windows native Scheduled Task has several benefits.

One benefit is that you can look at MyTrigger as an extention to Windows own Scheduled Task, MyTrigger just makes them a little better since it adds several new options to trigger a task. The second benefit is that it gives MyTrigger the abillity to tap in to the powerful existing UI and logging for executing tasks. If you need to have your task run i.e. in a special security context, only when the computer is idle or with a specific working folder, you can create a Scheduled Task that does just this. Then just configure MyTrigger to launch that task when the suitable trigger is fired.

4. What about security?

MyTrigger is a very powerful utility for your system. But you need to be aware of that it also introduces a new security risk. MyTrigger uses two different settings files that control the behavior. One file defines triggers for all users on the computer and is stored in a central location. The other file defines triggers for the currently logged on user and is stored in under the Application Data folder for the current user. Needless to say, if any of those two files are overwritten by an intruder, MyTrigger could end up executing a program of the intruder’s choice.

To mitigate this, MyTrigger uses cryptographic signing of the settings files. Each time you change the settings via the program, that is considered an acceptable change and the settings file is signed. The cryptographic keys that are used to sign the settings file are unique to each computer that runs MyTrigger. If an intruder manages to alter the content of the settings file, MyTrigger will detect this at the next startup and will refuse to start until the user has had the chance to review the settings and pressed OK to resign them. So, in order to use MyTrigger as a technique to start a program on your computer, the intruder must already be able to start a program (namely MyTrigger) on your computer.

The "All Users" settings file can only be signed by a member of the Administrator group on your computer.

If you have specific questions about how MyTrigger handles security issues or want to discuss specific changes, please feel free to contact us at support@torgesta.com.

5. How do I Install MyTrigger?

MyTrigger is delivered with an installation program, MyTriggerSetup.exe. Just start the installation prorgam from an account with administrative privileges.

6. Using MyTrigger

For the most of the time, using MyTrigger means just starting it. It will sit in the system Tray until you shut down your computer or right click the MyTrigger icon and select Exit. During installation, you can choose to place a MyTrigger shortcut in the startup folder so that it's always running when you're logged in.

But the first time you start MyTrigger, you probably want to add a couple of triggers. To do that you need to bring up the MyTrigger settings dialog.

Right click on the MyTrigger Icon in the System Tray, in the right bottom corner of your screen. Select "MyTrigger Settings" in the pop-up menu. This will show the Settings dialog.

6.1 Creating a WLAN trigger This type of trigger is used when you want a script or program to be launched when your computer connects to a WLAN access point. To create a WLAN trigger, follow these steps:

Open the MyTrigger settings dialog and select the "WLAN" tab.
Click on the "Add" button. Note, the administrator of your computer may not allow you to create your own rules. If so, the "Add" button is disabled.
Decide if you want the trigger to fire when your computer connetcts or disconnects from a WLAN by choosing the appropriate alternative in the "Wait for computer to" dropdown list.
Choose the WLAN you want to detect. If you can't find your WLAN name in the drop down list, you can just type the name in the edit box. If you want to create a trigger that fires for more than one WLAN, you can type in a suitable regular expression and check the Regular expression check box.
In the "Run command" edit box, type in the name of the command you want to run when your computer enters/connects to the network.
If you are an administrator and want this trigger to apply for all users on the computer, check the "Apply for all users" checkbox.
Click the "Save" button to save your new trigger.

The above screen shot shows how to add a WLAN trigger that launches the command script c:\mounthomedir.cmd when the computer connects to the MyHomeNetwork Access point.

6.2 Creating a USB trigger. This type of trigger is used when you want a script or program to be launched when your computer detects that a USB device has been inserted or removed from your computer. To create a USB trigger, follow these steps:

Open the MyTrigger settings dialog and select the "USB" tab.
Click on the "Add" button.
Decide if you want the trigger to fire when a USB device is inserted or removed by choosing the appropriate alternative in the "Wait for USB device to be" dropdown list.
In the "USB device name/id to trigger on" edit box, enter the name of the USB device you want to trigger on, or select one from the drop down list. The list contains USB devices currently known to the computer.
If you want MyTrigger to identify the device by ID rather than by name, check the "Trigger on id" checkbox. This is useful if you have several devices (i.e. USB flash memory) and you want different rules for different devices.
If you don't know the friendly name/id to use here, you can try letting MyTrigger detect it for you. When you have the USB tab open, insert or remove the USB device you want to trigger on. The "Last event" label should change to display the friendly name of the USB device you just inserted or removed:

Double click on the name of the USB device to copy it into the "USB device name/id to trigger on" edit box.
In the "Run command" edit box, type in the name of the command you want to run when your computer detects that the USB device is inserted or removed.
If you are an administrator and want this trigger to apply for all users on the computer, check the "Apply for all users" checkbox.

6.3 Creating a process trigger This type of trigger is used when you want a script or program to be launched when a process (program) have just started, stopped, is unresponsive or amok.

Open the MyTrigger settings dialog and select the "Process" tab.
Click on the "Add" button.
Decide if you want the trigger to fire when a process is started, stopped, unresponsive or amok (using all available CPU) by choosing the appropriate alternative in the "Wait for process to" dropdown list.
In the "Process name to trigger on" edit box, enter the name of the process you want to trigger on, or select an existing process from the drop down list.
If you don't know the exact name of the process you want to trigger on. You can easily find it. Start your computers Task Manager and select the "Applications" tab. Locate the program you're interested in and right click on in. In the context meny that shows, select "Go to process". This takes you to the "Processes" view where the your process of interest is highlighted.

In the "Run command" edit box, type in the name of the command you want to run when your computer detects that the process is started, stopped, unresponsive or amok.
If you are an administrator and want this trigger to apply for all users on the computer, check the "Apply for all users" checkbox.
Click the "Save" button to save your new trigger.

6.4 Creating a folder trigger This type of trigger is used when you want to monitor changes in a file system folder.

Open the MyTrigger settings dialog and select the "Folders" tab.

Click on the "Add" button.
In the "Folder to watch" edit box, enter the name of the folder you want MyTrigger to watch. Note that you can use the "..." button to navigate to the folder instead of typing it's name. If you want MyTrigger to monitor all subfolders as well, check the "Watch subfolders" checkbox.
If you want to include or exclude certain files, you may define a filter. You can define an including filter that only includes certain file types, or you can define an excluding filter that excludes certain files. You can use multiple filters by separating them with a semicolon. Type in the filter in the "Filter" edit box. For instance if you only want to trigger on changes in files with the "txt" extention, type in "*.txt" as filter and make sure the Include radio button is selected. If you want to trigger on changes in every type of file except cmd and bat files, type in "*.cmd;*.bat" as the filter and select the Exclude radio button.
In the "Execute command" edit box, type in the name of the command you want to run when a change in the folder is detected
Decide what types of changes you want to detect and check the suitable boxes:

Add

Rename

Delete

Modify

Metadata modify

Decide if you want to delay the trigger until the file is unlocked. By default, MyTrigger will fire a trigger as soon as it detects that the file is changed or added. In some cases this means that the trigger fires while another program or the operating system is still using the file. This may for instance happen when a large file is copied in to a monitored folder and the file transfer takes a few seconds to complete. MyTrigger can delay the trigger so that it doesn't fire until the file in unlocked. If you want this behaviour, check the "Delay trigger until the file is unlocked" checkbox.
If you are an administrator and want this trigger to apply for all users on the computer, check the "Apply for all users" checkbox.
Click the "Save" button to save your new trigger.

6.5 Creating an Event log trigger This type of trigger is used when you want a script or program to be launched when an entry is written in the computers Event log. Note that only administrator can monitor the Security event log.

Open the MyTrigger settings dialog and select the "Event log" tab.

Click on the "Add" button.
The Log file, Event source, Event type and Description fields allow you to define a filter for what Event log entries you want to trigger on. A blank field means that the field wont be part of the filter. If you want to trigger on every entry in all event logs, leave all fields blank.

Log file

Event source

Event type

Description

In the "Run command" edit box, type in the name of the command you want to run when the trigger fires.
If you are an administrator and want this trigger to apply for all users on the computer, check the "Apply for all users" checkbox.
Click the "Save" button to save your new trigger.

6.6 Creating a service trigger This type of trigger is used when you want a script or program to be launched when a service is started or stopped.

Open the MyTrigger settings dialog and select the "Services" tab.

Click on the "Add" button.
Decide if you want the trigger to fire when a service is started or stopped by choosing the appropriate alternative in the "Wait for service device to be" dropdown list.
In the "Service name to trigger on" edit box, enter the name of the process you want to trigger on, or select a service from the drop down menu.
In the "Run command" edit box, type in the name of the command you want to run when the service is started or stopped.
If you are an administrator and want this trigger to apply for all users on the computer, check the "Apply for all users" checkbox.
Click the "Save" button to save your new trigger.

7. Advanced usage

7.1 Regular Expressions

The normal behavior is for MyTrigger to require an exact match to trigger on i.e. a WLAN Access Point change. For greater flexibility, you can use a regular expression to define what Access point, USB device or process name MyTrigger should act on.

To use a regular expression instead of exact matches, you simply select the "Regular Expression" radio button when creating or editing a trigger. Here are some sample regular expressions you could use:

Trigger on... Regular expression

Any name staring with Foo Foo[.]*

Any name ending with Foo [.]*Foo$

Foo1 or Foo2 Foo[12]

Please note that the regular expression meta characters used differs slightly from the meta charaters that i.e. Perl uses. This is the complete list of valid meta characters and their meanings:

Metacharacter Meaning

. Matches any single character.

[ ] Indicates a character class. Matches any character inside the brackets (for example, [abc] matches "a", "b", and "c").

^ If this metacharacter occurs at the start of a character class, it negates the character class. A negated character class matches any character except those inside the brackets (for example, [^abc] matches all characters except "a", "b", and "c"). If ^ is at the beginning of the regular expression, it matches the beginning of the input (for example, ^[abc] will only match input that begins with "a", "b", or "c").

- In a character class, indicates a range of characters (for example, [0-9] matches any of the digits "0" through "9").

? Indicates that the preceding expression is optional: it matches once or not at all (for example, [0-9][0-9]? matches "2" and "12").

+ Indicates that the preceding expression matches one or more times (for example, [0-9]+ matches "1", "13", "666", and so on).

* Indicates that the preceding expression matches zero or more times.

??, +?, *? Non-greedy versions of ?, +, and *. These match as little as possible, unlike the greedy versions which match as much as possible. Example: given the input "<abc><def>", <.*?> matches "<abc>" while <.*> matches "<abc><def>".

( ) Grouping operator. Example: (\d+,)*\d+ matches a list of numbers separated by commas (such as "1" or "1,23,456").

\ Escape character: interpret the next character literally (for example, [0-9]+ matches one or more digits, but [0-9]\+ matches a digit followed by a plus character). Also used for abbreviations (such as \a for any alphanumeric character; see table below). If \ is followed by a number n, it matches the nth match group (starting from 0). Example: <{.*?}>.*?</\0> matches "<head>Contents</head>".

$ At the end of a regular expression, this character matches the end of the input. Example: [0-9]$ matches a digit at the end of the input.

| Alternation operator: separates two expressions, exactly one of which matches (for example, T|the matches "The" or "the").

! Negation operator: the expression following ! does not match the input. Example: a!b matches "a" not followed by "b".

Parameters

When MyTrigger launches a program, you can pass parameters to the program being launched. You do that by defining parameter placeholders in the enter/exit etc. commands associated with each trigger. MyTrigger will substitute your placeholders with the correct value at runtime. Each different type of trigger has a different set of parameters that can be passed. If you for instance want to pass the WLAN Access Point name (or more correctly SSID) to the program you start, you can use the following command:

Foo.cmd %NAME%

A WLAN trigger has the following valid parameters:

Placeholder Meaning

%NAME% The name/SSID of the WLAN Access point that just got connected or disconnected

A Process trigger has the following valid parameters:

Placeholder Meaning

%NAME% The filename of the executable of the process

%PATH% The full path to the executable

%CMDLINE% The full command line that was used to start the process.

%CAPTION% The caption of the process

%PID% The process identifier/PID

%ParentPID% The process identifier/PID of the parent process

%CREATED% Time stamp marking the creation time of the process

%TERMINATED% Time stamp marking the termination time of the process

A USB trigger has the following valid parameters:

Placeholder Meaning

%NAME% The "friendly" name of the USB device. I.e "USB 2.0 Mass storage device"

%DEVICEID% The device unique ID. This is a string based ID.

A Folder trigger has the following valid parameters:

Placeholder Meaning

%NAME% The path of the folder being watched

%FILE1% Name of the file or folder that was added/modified/removed. If the type of operation was RENAME, FILE1 is the old name of the file/folder.

%FILE2% If the type of operation was RENAME, FILE2 is the new name of the file/folder.

%TYPE% The type of change that caused the trigger to fire. One of the values ADD, MODIFY, DELETE or RENAME

An Event Log trigger has the following valid parameters:

Placeholder Meaning

%LOGFILE% Name of the log: Application|Security|System

%SOURCENAME% The name of the application/system that wrote the event.

%EVENTTYPE% Integer. Type of event, one of : 1 (Error) | 2 (Warning) | 3 (Information) | 4 (Security audit success) | 5 (Security audit failure)

%MESSAGE% Event message as it appears in the Windows NT event log.

%CATEGORYSTRING% Translation of the subcategory. (source-specific, see Category)

%CATEGORY% Subcategory for this event (Integer). (source-specific)

%COMPUTERNAME% Name of the computer that generated this event.

%EVENTCODE% Value of the lower 16-bits of the EventIdentifier property. It is present to match the value displayed in the Windows NT Event Viewer. Note that two events from the same source may have the same value for this property but may have different severity and EventIdentifier values.

%EVENTIDENTIFIER% Identifier of the event. This is specific to the source that generated the event log entry and is used, together with SourceName, to uniquely identify a Windows NT event type.

%RECORDNUMBER% Identifies the event within the Windows NT event log file. This is specific to the log file and is used together with the log file name to uniquely identify an instance of this class.

%TIMEGENERATED% When the source generated the event.

%TIMEWRITTEN% When the event was written to the logfile.

%TYPE% String. Type of event, one of : Error | Warning | Information | Security audit success | Security audit failure. See EventType.

%USER% User name of the logged-on user when the event occurred. If the user name cannot be determined, this will be the empty string.

A Service trigger has the following valid parameters:

%NAME% Unique identifier of the service that provides an indication of the functionality that is managed. This functionality is described in more detail in the Description parameter.

%CAPTION% Short description of the object—a one-line string.

%DISPLAYNAME% Display name of the service. This string has a maximum length of 256 characters.

%ACCEPTPAUSE% Boolean (0|1). Service can be paused.

%ACCEPTSTOP% Boolean (0|1). Service can be stopped.

%CHECKPOINT% Value that the service increments periodically to report its progress during a long start, stop, pause, or continue operation.

%DESCRIPTION% Long description of the service.

%DESKTOPINTERACT% Boolean (0|1). Service can create or communicate with windows on the desktop.

%EXITCODE% Windows error code defining any problems encountered in starting or stopping the service.

%INSTALLDATE% Date object is installed.

%PATHNAME% Fully-qualified path to the service binary file that implements the service.

%PROCESSID% Process identifier of the service.

%SERVERSPECIFICEXITCODE% Service-specific error code for errors that occur while the service is either starting or stopping.

%SERVICETYPE% Type of service provided to calling processes. One of "Kernel Driver" | "File System Driver" | "Adapter" | "Recognizer Driver" | "Own Process" | "Share Process" | "Interactive Process"

%STARTED% Boolean (0|1). Service has been started.

%STARTMODE% Start mode of the Windows base service. One of: "Boot" | "System" | "Auto" | "Manual" | "Disabled"

%STARTNAME% Account name under which a service runs.

%STATE% Current state of the service. One of: "Stopped" | "Running"

%STATUS% Current status of the service. One of: "OK" | "Error" | "Degraded" | "Unknown" | "Pred Fail" | "Starting" | "Stopping" | "Service"

%SYSTEMNAME% Name of the system that hosts this service.

%TAGID% Unique tag value for this service in the group.

The settings files

MyTrigger uses two settings files, both named settings.ini. They are stored in the "Application Data\MyTrigger" for the current user profile and the All Users profile. On XP these folders are typically located at C:\Documents and Settings\[user name]\Application Data\MyTrigger and C:\Documents and Settings\All Users\Application Data\MyTrigger. The settings files are classic Windows .ini file with sections marked by [secion name]. Example:


[GENERAL]
FileVersion=2
RegName=JOVS1IVF
RegCode=DBJS5-BFV3Z-GG34H-TT2Z2

[FOLDER]
FolderName1="C:\src\cvsroot.torgesta.com\torgesta.com\MyTrigger\doc\source"
Filter1="*.txt"
ModCommand1=C:\src\cvsroot.torgesta.com\torgesta.com\MyTrigger\doc\source\WikiTransform.vbs
unused1=0
Option1=9
TriggerCount1=1

Only one instance of MyTrigger will handle the All Users settings file. This means that if you start MyTrigger two times, only the first instance of the program will act on the settings in the All Users settings file. This is to make sure that All User triggers doesn't fire several times if several users are logged on at the same time or if MyTrigger is also running as a service.

Signing the settings files

MyTrigger uses cryptographic signing of the settings files so that if the files are overwritten without resigning them, MyTrigger will not read the settings. See What about security?. If you want to alter the settings files programatically, you can sign them without starting the MyTrigger UI by starting MyTrigger with the -sign command line parameter.

Example:

c:\program files\MyTrigger\MyTrigger.exe -sign

MyTrigger will detect when one of the two settings files are modified. If a settings file is modified and the file is correctly signed, it will read the new settings and apply them. Note that in order to sign the All Users settings file, you must be an administrator on the computer.

Hiding the tray icon

In some situatios you may want to run MyTrigger without the tray icon showing. This can be done by adding the line ShowTrayIcon=0 in the settings file's GENERAL section:

[GENERAL]
ShowTrayIcon=0

An administrator may also do the opposite and force the tray icon to be visible by adding ShowTrayIcon=0 in the GENERAL section of the All Users file:

[GENERAL]
ShowTrayIcon=1

If the ShowTrayIcon setting is present in the All User settings file, it can not be altered in the current users setting file. To close a running instance of MyTrigger that doesn't have a visible tray icon, run MyTrigger with the -closeall command line parameter.

Closing running instances

To close all running instances of MyTrigger, run MyTrigger with the -closeall command line parameter:

Example:

c:\program files\MyTrigger\MyTrigger.exe -closeall

This will close all running instances, including invisible, that runs in the same desktop that the current user. This means that an instance that is running as a service will not be affected.

8. Running MyTrigger as a service

MyTrigger can be installed to run as a system service. That means that MyTrigger will start when the computer starts and will run as long as the computer is running. There's no need for a user to log on to the computer. This is useful if you want to use MyTrigger to monitor events on a server computer where typcally no user will be logged on. Important! When MyTrigger is running as a service, it will only handle the triggers that are defined for All Users. This is regardless of what account you define for the service to run under.

To install and run MyTrigger as a service, install MyTrigger normally and then run the MyTrigger Service Wizard found on the Start menu->Programs->MyTrigger->Install MyTrigger as a service. Note that you must be an administrator on the local machine to successfully install the service.

The wizard will help you install the service and make sure it runs under a suitable user account. Note that since the programs and scripts that MyTrigger launches is run in the security context of the user that started MyTrigger, it's not suitable to let the MyTrigger Service run under the Local System account. Also note that the account you choose does not have to have administrative privileges, any user account will do.

At the end of the wizard, you should test the service to make sure that it can start before you exit the wizard. If the service can't start, you will get an error message explaining why. If the service will not start when you are testing from the wizard (running with administrative privileges), it will not start when the computer is rebooted. If the wizard detects that the user account you supply does not have the "Log on as a service" privilege, the wizard will give that privilege to the selected user account.

When MyTrigger is running as a service, it can be started and stopped in the same way as any other system service. Any user logged on to the computer can start additional "normal" instances of MyTrigger, the only difference is that those instances will not fire the All Users triggers, they are already handled by the service.

9. The log file

Every event that leads to that MyTrigger launches a program is logged in a log file. The log file is stored at: C:\Documents and Settings\[username]\Application Data\MyTrigger\MyTrigger.log where [username] is the name of the user context that MyTrigger runs in. To view the log file, just right click on the MyTrigger icon in the system tray and select "View log file..." from the menu.

10. Feedback and reporting errors

If you find a bug or have other problems with MyTrigger, we want to hear from you. The best way to get in touch with us is via email: support@torgesta.com. We also welcome suggestions about what features or changes that would make MyTrigger a more useful product for you.