pmctl

Name

pmctl — control tool.

Synopsis

pmctl [-h] [-v] [-u URL] [-b service name] [-d service domain] [-i interface property file…] [-I interface property file…] [-r request…] [-p name=value…] [-c { integer boolean date } …] [-l username] [-k URL] [-s] [-S URL] [-t { 4 6 } ] [-f { plist perl json } ] [-w seconds] shorthand notation…

Description

pmctl is a tool for managing Power Manager.

pmctl is used to connect to and control Power Manager. pmctl is the main command line tool for interacting with local and remote Power Manager instances.

pmctl can send requests to Power Manager. Responses can be displayed in a range of common formats.

pmctl will connect to the default instance of Power Manager. If no URL is provided, the default is used. The default is typically the local instance of Power Manager.

A provided URL must include a scheme prefix, often known as a protocol. Supported schemes include file:// and pm://. File schemes must be absolute; that is, the file path must begin with /.

IPv6 shorthand notation is supported. The IPv6 loopback address can be written as [::1].

./pmctl
./pmctl -u pm:///var/tmp/uk.co.dssw.powermanager/pmd
./pmctl -u pm://192.168.1.1:8765
./pmctl -u pm://[::1]:9876

A range of URL schemes are supported by pmctl

pmctl can connect to Bonjour/ZeroConf advertised Power Manager services. Use the b flag to provide the service name to resolve and connect to. If a service name is provided in additional to a URL, the service name will be used.

By default, Bonjour service name resolution occurs within the local. domain. Use the d flag to provide an alternative domain to resolve service names with.

./pmctl -b 'Mac Pro'
./pmctl -b 'Mac Pro' -b 'services.university.edu'

Bonjour/ZeroConf is supported by pmctl

./pmctl -r build.version

Get the version details of the local Power Manager instance.

Sets of parameters can be associated with a request. A parameter consists of a name and value pair.

-p name=value

Base parameter format.

./pmctl -r scheduler.setenabled -p enabled=true

Enable the scheduler with a request and parameter.

Where multiple requests are issued, parameters are associated with the last request. If no request has yet been specified, parameters are associated with the first request. The following commands are equivalent:

./pmctl -r scheduler.setenabled -p enabled=true
./pmctl -p enabled=true -r scheduler.setenabled

These commands are equivalent.

Parameters containing spaces must be quoted to avoid the shell splitting the contents:

./pmctl -r scheduler.remove -p 'unique ID=Weekend Sleep'

Parameters with spaces must be quoted.

Preprocessed Parameters

Parameters may be preprocessed using parentheses. Preprocessed parameters expand the range of input pmctl can use when building a request. They allow for parameters to be read from files, remote resources, and for pass phrases to be securely requested from the command line.

Some complex parameters must be preprocessed. These parameters include those that require structures or arrays.

./pmctl -r scheduler.set -p 'event=(plist:file:///Users/Shared/event.plist)'

Set an event using the contents of a local property list file.

Property List Parameters

A parameter can be a property list (plist). Property list files contain XML structured contents and are common on macOS. To associate the contents of the property list with a parameter, use the plist preprocessor:

-p ’name=(plist:URL)’

Base property list parameter format.

The URL may refer to local or remote resources:

./pmctl -r scheduler.set -p 'event=(plist:file:///Users/Shared/event.plist)'
./pmctl -r scheduler.set -p 'event=(plist:http://www.example.com/event.plist)'
./pmctl -r scheduler.set -p 'event=(plist:https://www.example.com/event.plist)'
./pmctl -r scheduler.set -p 'event=(plist:ftp://ftp.example.com/event.plist)'

A range of URL schemes are supported for getting property lists.

URLs may be escape encoded. Relative file scheme URLs are evaluated using the current working directory as the base location.

Raw Parameters

A parameter may need to include contents that match pmctl’s preprocessing format. To avoid preprocessing content, use the raw preprocessor:

-p ’name=(raw:contents)’

Base raw parameter format.

The brackets and prefixed raw will be removed, but the contents will be untouched and passed through as the parameter.

If an event has the unique ID (plist:file:///tmp/), the following command will issue an appropriate remove request:

./pmctl -r scheduler.remove -p 'unique ID=(raw:(plist:file:///tmp/))'

Remove an event with the unique ID: (plist:file:///tmp/).

Multiple Requests

Multiple requests can be sent by concatenating requests flags. A single connection is created and the requests are issued in the order provided on the command line.

pmctl sends all the requests immediately. pmctl does not wait for the response from the first request, before sending the next. It is possible, and likely for time consuming requests, that responses will be returned out of sequence.

Responses to multiple requests are grouped and output as a list.

./pmctl -r build.version -r notifications.warningperiod -r notifications.notifyperiod
["uk.co.dssw.powermanager.pmd v4.0.0",3,900]

Multiple requests are supported. Responses are returned as lists.

Character Encoding

All character encoding and input is assumed to be UTF8. Providing input in other encodings may adversely affect pass phrase digests, leading to failed authentication.

UTF8 encoding is the default for macOS’s Terminal.app application.

Interfaces

Interface files describe the structure and expectations of a request and its associated parameters. pmctl uses interface files to coerce parameters into the appropriate format.

Interface files are located within the Power Manager Support folder. By default, pmctl will include all interface files found within the interfaces folder. Additional search paths can be provided via the command line flag i, or an exclusive search path can be provided via the command line flag I.

./pmctl -i '/Users/Shared/Additional Interfaces'

Add /Users/Shared/Additional Interfaces to interface search paths.

./pmctl -I '/Users/Shared/Interfaces'

Only search /Users/Shared/Interfaces for interface files.

Parameter Coercion

Parameters need to passed to Power Manager in specific formats. All parameters provided directly from command line arguments are strings; in many cases strings are not the appropriate format.

Type coercion is limited in the possible conversions that can be performed. Where a conversion is not possible, the original parameter is left untouched. In this situation the request is expected to fail with an error message explaining which parameter is invalid.

Automatic Coercion

pmctl automatically coerces parameters into the appropriate format. This automatic coercion is directed by the interface file. If the request to be sent has an entry in the interface files, then pmctl reviews each parameters and performs type coercion as required.

Manual Coercion

pmctl can be coerce parameters manually using the command line flag c. You should rarely need to manually coerce parameters, but the functionality is available where requests are not available in the interface files.

./pmctl -r scheduler.setenabled -c boolean -p enabled=true

Coerce the parameter enabled from a string to a boolean.

Supported Type Coercions

Available Type Coercions

integer

string

string

(none)

boolean

number (yes != 0)
string (yes/no,y/n,true/false,t/f,1/0)

date

number (absolute time)
string (local short date and time format,seconds relative date)

Example 2.1. Integer coercions

Example 2.2. Boolean coercions

Example 2.3. Date coercions

Security

pmctl provides a secure connection to Power Manager.

pmctl does not accept passwords via the command line. You must provide a password via the Keychain, or interactively.

The preferred method of providing a username and password is via the Keychain.

Keychain Support

pmctl supports storing and retrieving connection authentication details - your username and password - from the current Keychain. The Keychain is an Apple technology for securely managing sensitive information, such as passwords and pass phrases.

To add a connection’s details to the Keychain, use the command line flag k followed by the connection’s URL.

./pmctl -k pm://192.168.1.1:1234
Login: jane
Password:

Adding a username and password for pm://192.168.1.1:1234 to the current Keychain.

pmctl will subsequently automatically retrieve and use the stored Keychain pass phrase for this connection.

./pmctl -n jane -u pm://192.168.1.1:1234

Use the password associated with jane in the current Keychain.

Secure Sockets Layer (SSL)

Power Manager connections are protected by Secure Sockets Layer (SSL) technology. pmctl transparently handles establishing and maintaining a secure connection.

SSL support is required and can not be disabled. Power Manager does not support unencrypted connections.

By default, expired or self-signed certificates are accepted by pmctl. This allows Power Manager to offer encrypted connections where no certificate is available; a one time self-signed certificate is created as needed.

Where Certificate Authority signed and certified certificates are used, you may wish to override and enforce stricter SSL settings. Use the command line flag S to provide a URL to an SSL settings property list file.

./pmctl -S file:///Users/Shared/ssl/encryptiononly.plist -u pm://192.168.1.1:1234

Provide the connection with custom SSL options.

{
    "peer name" = "";
    allow = (
        "any root",
        "invalid certificate chain",
        "expired root certificates",
        "expired certificates",
    );
    level = negotiated;
}

SSL settings allowing self-signed certificates.

The contents of the SSL settings property list file match the contents of the SSL structure: see the Power Manager Developer documentation for more information.

Supporting IPv6

pmctl supports connections using IPv4 and IPv6.

When resolving a hostname, pmctl may be provided with a list of resolved addresses including both IPv4 and IPv6 protocols. By default, pmctl prefers the IPv4 protocol and will attempt to connect to the first IPv4 address returned. IPv4 is the most widely used protocol today.

In mixed IPv4 and IPv6 environments, pmctl can be told to prefer IPv4 or IPv6 using the command line flag t. With the -t 6 flag set, pmctl will attempt to connect to the first IPv6 address returned.

The t command line flag is a preference only; if the preferred protocol is not returned, pmctl will connect to next best alternative.

./pmctl -t 6 -u pm://mymac.local.:1234

Prefer IPv6 resolved addresses.

Output Formats

pmctl provides request responses in a selection of easy to parse formats. These formats include XML/Property List, Perl and JavaScript Object Notation (JSON).

Use the command line flag f to set the output format.

./pmctl -f plist -r build.version
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<string>uk.co.dssw.powermanager.pmd v4.0.0</string>
</plist>
./pmctl -f json -r build.version
"uk.co.dssw.powermanager.pmd v4.0.0"
./pmctl -f perl -r build.version
"uk.co.dssw.powermanager.pmd v4.0.0"

A range of output formats are available.

Structured Perl

Output formatted for Perl can be passed directly to the eval function. The result is an instigated variable within the Perl script ready for direct manipulation.

#!/usr/bin/perl

use warnings;
use strict;

# Get the list of pending triggers - this snippet assumes at least one trigger
my $pending = eval(`./pmctl -r notifications.pending`);

# Get the trigger ID of the next pending trigger; pending triggers are date ordered
my $next_trigger_id = $pending->{'response'}[0]{'trigger ID'};

# Request the trigger is adjusted to fire ten minutes from now
`./pmctl -r notifications.adjust -p 'trigger ID=$next_trigger_id' -p 'date=900'`;

Perl script to adjust the next trigger to ten minutes from now.

Timing Out

Hostname resolution and remote connections can take a while to resolve and reply. By default pmctl will wait a maximum of two minutes before timing out and exiting with an error status.

Use the command line flag w to provide a custom maximum time to wait for responses. The parameter is in seconds from the time the connection is created.

./pmctl -w 15 -u pm://remote.example.com:1234 -r scheduler.events

Time out after 15 seconds, if the request scheduler.events has no response.

Shorthand Notation

pmctl supports a shorthand notation for writing requests and parameter pairs. This notation exists to offer a more natural syntax for issuing requests via pmctl.

The shorthand notation allows requests and parameters to be appended to the end of a pmctl command without the r and p flags.

./pmctl build.version
./pmctl scheduler.setenabled enabled=false

A shorthand notation can be used, allowing the dropping of flags r and p.

No flag may appear after a piece of shorthand notation has been used. Make sure all command line flags appear before the shorthand.

Return Values

pmctl returns EXIT_SUCCESS if a connection is established. EXIT_FAILURE is returned if no connection could be established, or authentication failed.

The return value can be used to test if Power Manager is available locally, or at a specified address.

#!/bin/sh

`./pmctl`
if [ "$?" -ne "0" ]; then
  echo "Power Manager is not available"
else
  echo "Power Manager is available"
fi

Shell script to test pmctl’s return value.

#!/bin/sh

`./pmctl -u pm://192.168.1.1:1234` && ( echo "Power Manager is available" ) || ( echo "Power Manager is not available" )

One line shell script to test pmctl’s return value.

Files

Power Manager.app/Contents/Tools/pmctl