35. Writing sub-host plugin programs

Read this section to learn how to write a custom sub-host plug-in for your environment.

The sub-host plug-in is a Win32 console executable program that accepts information on standard input and writes results to standard output.

The input information includes:

• The ID of the end-user whose password is to be reset.
• A list of all target systems in the current reset request.
• Details of the target system that triggered the plugin. You can request a reset on multiple targets, but the plugin is only responsible for providing a list of sub-hosts for one real target.
• The name of the CGI program that called the plugin.

The CGI reads a list of all servers for the triggering host. P-Synch may reset passwords on each of the servers in this list.

The input and output are passed as plain text, in key-value format. Keywords and values are separated by whitespace, but extra whitespace between them should be ignored. Values are quoted strings.

Following is an example of the input that P-Synch ``types'' into the plugin program:

  trigger_host = "PLUGHOST"
  trigger_user = "JOHNDOE"
  trigger_alias = "jdoe"
  trigger_ip = "192.168.1.1"
  cgi_program = "nph-psa.exe"
  host = {
    host_id = "PLUGHOST"
    host_name = "Test Plugin host"
    host_type = "win2k"
    host_address = "\\TESTHOST"
    host_adminid = "psadmin"
    host_adminpass = "my_password"
  }
  host = {
    host_id = "OTHERHOST"
    host_name = "Another host"
    host_type = "unix"
    host_address = "other.domain.com"
    host_adminid = "psadmin"
    host_adminpass = "my_password"
  }

See TABLE: [SUBHOST/KEYS] for definitions of the input key-value pairs.

Table:Definitions of keys used in the sub-host plug-in input file.

This key...	Is associated with this input...
trigger_host	The ID of the host, or target system, that triggered this plugin.
trigger_user	The P-Synch ID of the user whose password is to be reset.
trigger_alias	The name of the account, on the trigger target system, that is owned by this user.
trigger_ip	The IP address of the user that requested this reset. This field is only set for self-service requests. Help desk resets will set this field to ``unknown''.
cgi_program	The name of the P-Synch component (CGI, service) that called the plugin.
host	A block of key-value pairs that defines a host. More than one host block may appear, but at least one block must correspond to the trigger_host defined above. The key-value pairs are enclosed in curly braces. The block consists of the key-value pairs below.
host_id	The ID of this target system.
host_name	The full name of this target system.
host_type	The type of this target. See TABLE: [HOSTTYPES] for a full list of host types keywords.
host_address	The address of this target.
host_adminid	The administrator login ID for this target.
host_adminpass	The administrator password for this target.

Following is an example of the output that the plugin should produce:

  out_host = {
    out_id = "OUTPUT1"
    out_name = "Server One"
    out_type = "win2K"
    out_address = "\\server1"
    out_adminid = "psadmin"
    out_adminpass = "my_password"
    out_select = "true"
  }
  out_host = {
    out_id = "OUTPUT2"
    out_name = "Server Two"
    out_type = "unix"
    out_address = "\\server2"
    out_adminid = "psadmin"
    out_adminpass = "my_password"
    out_select = "false"
  }

See TABLE: [SUBHOST/OUTPUT] for definitions of the output key-value pairs.

Table:Definitions of keys appearing in the sub-host plug-in output file.

This key...	Is associated with this output...
out_host	A block of key-value pairs similar to the host block used as input. At least one out_host block must appear in the output. The block consists of the key-value pairs below.
out_id	An identifier for this server.
out_name	The full name for this server.
out_type [4] (Optional)	The type of this server. Use this key-value pair if the sub-host server type is different to the target system type. See TABLE: [HOSTTYPES] for a full list of host types keywords.
out_address	The address for this server. This address must use an address syntax appropriate for the host type of the trigger system.
out_adminid [4] (Optional)	The administrator login ID for this server. Use this key-value pair if the ID is different to the one entered in the input file.
out_adminpass (Optional)	The administrator password for this server. Use this key-value pair if the password is different to the one entered in the input file.
out_select	If ``true'', this server is selected by default on help desk selection screens. If ``false'', this server is deselected by default.