PIKT is managed through the combined action of the interactive control program, piktc (on the central master machine only), and the piktc_svc service daemon (on all client machines).
Here are the piktc command options:
Usage: piktc <-bBcCdefGhiIkKlLm#MprRstTvVwWxXZ>
[+|-D <define(s)>]
[+|-E <envar(s)>]
[+C <command(s)>]
[+M <macro(s)>]
[+|-A|S[f] all|<alert(s)/script(s)>]
[+|-P[f] all|<program(s)>]
[+|-F[f] all|<file(s)>]
[+|-O[f] all|<object(s)>]
+|-H all|<host(s)>
[ALL]
-b backup alert/script/program/file/object
file(s)
-B restore alert/script/program/file/object
file(s) from backup
-c syntax check all config files
-C syntax doublecheck all config files
-d disable alert(s)
-e enable alert(s)
-f diff alert/script/program/file/object
file(s)
-G run in debug mode
-h show program help
-i install alert/script/program/file/object
file(s)
-I update #include/#verbatim files
-k kill alert daemon (piktd)
-K kill service daemon (piktc_svc)
-l list alert/script/program/file/object
file(s)
-L list alert/script/program/file/object or
host/os/group/alias command-line item(s)
-m# checksum alert/script/program/file/object
file(s), where # is checksum level 1-5
-M expand macros
-p install PIKT.conf
-r (re)start alert daemon (piktd)
-R (re)start service daemon (piktc_svc)
-s show alert(s) status
-t delete alert/script/program/file/object
/history/log file(s)
-T run in test mode
-v run in verbose mode
-V show version info
-w view alert/script/program/file/object
actual file(s)
-W view alert/script/program/file/object
authorized file(s)
-x execute alert(s)/script(s)
-X execute alert(s)/script(s) with no wait
-Z list all config elements
+|-D <define(s)> define/undefine define(s)
+|-E <envar(s)> set/unset environment variable(s)
+C <command(s)> include command string(s)
+M <macro(s)> include macro string(s)
+|-A|S[f] all|<alert(s)> include/exclude (fix) alert(s)
+|-P[f] all|<program(s)> include/exclude (fix) program file(s)
+|-F[f] all|<file(s)> include/exclude (fix) other file(s)
+|-O[f] all|<object(s)> include/exclude (fix) object file(s)
+|-H all|<host(s)> include/exclude host(s)/os(es)/group(s)/
alias(es)
ALL +A all +S all +P all +F all +O all +H all
By specifying -b, whenever you install or delete files (or refresh PIKT.conf), piktc_svc will make a backup of the files first (with a file extension you specify using backup_extension in PIKT.conf, else the default is ".piktbak"). The backup option is especially useful when overwriting system configuration files during an initial PIKT setup (for example, when installing a PIKT-managed inetd.conf). If you goof up, you can revert to the backup copy.
With the -B option, you restore files from backup. On the piktc command line, specify alerts, scripts, programs, files, and/or objects (using the A, S, P, F, and/or O options) in the usual way but without giving any backup extension (e.g., use '+F inetd.conf' instead of '+F inetd.conf.piktbak'). A restore will replace the most recent file with its .piktbak backup (or whatever backup_extension you specify in PIKT.conf). (Note that, although the -b option works with the -p option, install PIKT.conf, you cannot use -B to restore an earlier PIKT.conf. You would still have to do this manually.)
With the -c option, piktc syntax checks all config files for one or more hosts.
The -C option has piktc do its usual syntax check, then invoke pikt to do a second, more thorough syntax check. A -C check takes significantly longer than a -c check. You will will probably want to select -C after making major changes to your config files, and -c after spot changes.
The -e option enables alerts, and the -d option disables them. Enablement registers an alert (or alerts) in the file =piktdir/etc/piktd.conf. (Refer to the sample piktd.conf file.) Disablement removes an alert (or alerts) from that file. piktd.conf is the file that piktd reads on startup. It tells piktd what alerts to run and when (among other information).
After enablement/disablement, an alert doesn't become active/inactive until, using the -r option (else a manual daemon restart or a system reboot, if you have so configured the system startup scripts), piktc (re)starts the client piktd daemon.
With the -f option, piktc fetches files from the client machine(s) and diff's them against the master configuration. This is useful during initial setup, for catching client-side changes made bypassing the usual PIKT operation, also for detecting file changes perhaps done by a hacker.
The -G option turns on debugging. Debug messages are sent to stderr.
The -h option shows program help (shown above).
The -i option installs alert/object/programs files on clients. Installation places alerts in =piktdir/lib/alerts, object files in =piktdir/lib/objects, and program files in =piktdir/lib/programs. However, you can override the default program installation directory by using a full file path as the program stanza identifier.
The -I option has piktc update the on-disk #include or #verbatim files with associated process output.
In other words, suppose your systems.cfg contained
#verbatim <systems/downsys_systems.cfg> [/pikt/lib/programs/downsys.pl 10]
If you specify the '-I' (for "update include files") piktc option, as in
# piktc -cI +H piktmaster
this will read from [/pikt/lib/programs/downsys.pl 10] and write that process output to the file <systems/downsys_systems.cfg>. If you omit the '-I' option, piktc will just reference the <systems/downsys_systems.cfg> file.
Although you could use the '-I' routinely in all of your piktc commands, of course you shouldn't, for that would slow your piktc operations down dramatically. Better to do this just occasionally, say once a day (overnight) only.
To auto-update your configuration and refresh your scripts and data sets with the very latest and most accurate information on all systems, you could regularly schedule (e.g., nightly) the sequence
piktc -cI +H piktmaster
piktc -iv ALL
either by cron'ing it or by having PIKT itself run it on the piktmaster machine.
Here is a short Pikt script to auto-update your #include and #verbatim files (as it would appear in alarms.cfg):
#if piktmaster
UpdateIncludeFilesAdmin // auto-update the PIKT #include|#verbatim
// files
exec wait "=piktc -cI +H piktmaster"
#endif // piktmaster
You might run this together with your other Admin scripts (from alerts.cfg):
#if piktmaster
Admin // for scripts aiding in the administration of
// the PIKT system
timing 30 3 * * * 5
mailcmd "=mailx -s 'PIKT Alert on =pikthostname:
Admin' =piktadmin"
scripts
UpdateIncludeFilesAdmin
...
#endif // piktmaster
Here is one way you might auto-configure your Solaris 2.8 systems in systems.cfg:
solaris28
members
#verbatim <systems/solaris28_systems.cfg>
[for sys in `/pikt/bin/piktc -L -H downsys`;
do /pikt/lib/programs/maxtime.exp 10 /usr/bin/ssh $sys "uname -a |
egrep 'SunOS.+ 5.8' >/dev/null && hostname"; done 2>/dev/null]
The preceding will work, but here is a more convenient way:
solaris28
members
#verbatim <systems/solaris28_systems.cfg>
[/pikt/bin/piktc -xI +C "=uname -a | =egrep 'SunOS .+ 5.8'
>/dev/null && =hostname" -H downsys 2>/dev/null]
(piktc deals with timeouts automatically, making explicit use of maxtime.exp unnecessary.)
If you are running piktc and referencing an #include (or #verbatim) process [/pikt/bin/piktc ...], you will be running two concurrent piktc's. Under ordinary circumstances, there are mechanisms in place to prevent multiple, concurrent piktc program runs. However, using the -I option, as in [/pikt/bin/piktc -xI ...], makes concurrent runs possible. If you fail to use the -I option in your [/pikt/bin/piktc -x ...] process, the embedded piktc run will simply abort.
You kill remote piktd daemons using the -k option. The -r option both kills and restarts.
You kill the remote piktc_svc daemon with the -K option. The -R option both kills and restarts. (See the restart_piktc_svc_wait parameter in the PIKT.conf section below.)
The -l option lists config files on remote clients.
The -L option is used for generating command-line item lists.
To login to just your HP-UX machines, for example, you could
# for sys in `piktc -L +H hpux`
> do
> slogin $sys
> done
since 'piktc -L +H hpux' simply outputs a list of hpux systems as specified in systems.cfg.
Or, you might put `piktc -L +H ... -H ...` statements in your shell (and other) scripts when you need to refer to custom system lists.
You can also list PIKT alerts/scripts, programs, files, and objects, for example
# piktc -Lv +S all +H vienna
processing vienna...
listing item(s)...
EMERGENCY
Urgent
Critical
...
Note that in the above example, those are Pikt scripts in the central configuration (the .cfg files), not scripts actually installed on the slave system (the .alt files).
The option -m[1-5] is used for doing checksum compares of slave alert/object/program/other files against the master's central configuration (the .cfg files). So you may do things like this:
vienna# piktc -m5v +A all +H kiev0 [uses the MD5 checksum]
processing kiev0...
checksumming file(s)...
Admin.alt checksummed
Critical.alt checksums differ
Critical.alt checksummed
Debug.alt checksummed
EMERGENCY.alt checksums differ
EMERGENCY.alt checksummed
Info.alt not found
Info.alt not checksummed
Notice.alt checksummed
Urgent.alt checksummed
Warning.alt checksummed
Omitting the '-v' verbose option:
vienna# piktc -m5 +A all +H kiev0
Critical.alt checksums differ
EMERGENCY.alt checksums differ
Info.alt not found
The above examples show that both the Critical and EMERGENCY alert scripts differ from the central configuration, possibly because legitimately changed versions have yet to be installed, or possibly because a cracker has tampered with those script files. Info.alt is missing, even though it is present in the central configuration.
You may use -m1 through -m5 for any of the five supported checksums (BSD, SysV, POSIX, MD4, MD5).
You can use the -M and +M options to macro-expand any given string, for example
# piktc -M +M "=uptime; =dfk" +H kiev murmansk
/usr/bin/uptime; /usr/bin/df -k
/usr/ucb/uptime; /bin/df
(where kiev is a Solaris machine and murmansk is a Debian system).
When used with the -M option, +M and +C are interchangeable, so the above piktc command is equivalent with
# piktc -M +C "=uptime; =dfk" +H kiev munich
The -p option installs PIKT.conf. See the keys.conf section of this Reference for further details.
The -r option both kills and restarts the piktd daemon.
The -s option reports whether an alert (or alerts) is (are) running on the remote client(s).
The -t option deletes files, as well as any history/log files associated with the deleted alert(s).
The -T runs piktc in test mode. You ordinarily wouldn't do this outside the installation 'make check'.
The -v option turns on verbose mode, telling the client-side piktc_svc to provide feedback as to the success or failure of an operation.
The -V option will output version information, e.g., "PIKT piktc version 1.18.0".
The -w option allows you to view files (alerts, programs, objects, etc.) as they actually appear on clients.
The -W option allows you to view files (alerts, programs, objects, etc.) as they are specified in the PIKT configuration (in the piktmaster's .cfg file). You may also redirect 'piktc -W' output to a different file name or pipe, say to scp or do something else with it.
The -x option tells piktc to direct the client-side piktc_svc to execute the indicated scripts or alerts. This is useful, for example, for restarting inetd after installing a new inetd.conf.
The -X option is like -x except that piktc doesn't wait for any feedback from a client before proceeding to the next. You would use -X when you are in a hurry, and -x when you need to know the result of a piktc command.
Using the -Z option, you can have piktc list all config file elements (stanza identifiers).
You can use piktc for remote program execution as an alternative to rsh or ssh. The command
# piktc -xv +C "<command string(s)>" +H <systems>
executes the <command string(s)> on the specified <systems>, with command feedback, while
# piktc -Xv +C "<command string(s)>" +H <systems>
does the same thing but without on-screen feedback (and without any wait).
You can insert PIKT macros within +C command strings. Because this forces piktc to parse the macros.cfg file, using macros in this way is slower than doing without. So, this
# piktc -xv +C "ls -l /var/spool/mail" +H all
would be faster than this
# piktc -xv +C "=ll =maildir" +H all
Of course, in the first example, if some of your systems have the mail spool directory as /var/mail, the command will fail--hence the advantage of the second example.
You can execute more than one command at a time, either by separating them by a semicolon within a single command string, else by separating them into more than one distinct command string. In other words, both
# piktc -xv +C "=rm -rf /tmp/SAS*; =du -sk /tmp" +H perf
and
# piktc -xv +C "=rm -rf /tmp/SAS*" "=du -sk /tmp" +H perf
achieve the same thing.
However, this
# piktc -xv +C "cd /var/tmp; =ll" +H perf
is not the same as this
# piktc -xv +C "cd /var/tmp" "=ll" +H perf
because in the second case the commands are executed in two separate subshells, and the directory change in the first command would not apply to the 'ls -l' command of the second (so the listing you would get in the second command string would be unpredictable).
You can combine, in a single 'piktc -x|X' command, +C and +|- A|S. For example, on the machine warsaw,
# piktc -xv +C "=rm =logdir/* =hstdir/*" +S TouchPiktVarFiles +H warsaw
will empty the contents of the PIKT log and histories directories, then create empty (zero-length) files for all registered log and histories files (if you you wanted to start afresh after installing new PIKT binaries, say).
Note, however, that +C command strings are always executed before +A or +S (or -A or -S) Pikt scripts.
Here is a sample 'piktc -xv +C' command with feedback:
# piktc -xv +C "=ll /etc/nologin" +H fac
processing kiev...
executing command(s)...
/etc/nologin: No such file or directory
"/bin/ls -l /etc/nologin" executed
processing kiev2...
remote piktc_svc not running
processing kiev0...
executing command(s)...
-rw-r--r-- 1 root staff 0 Jul 24 15:47 /etc/nologin
"/bin/ls -l /etc/nologin" executed
Here is an alternative form (without '-v' and adding =hostname and echo to the command line) resulting in reduced clutter (but note the absence of feedback about piktc_svc not running on kiev2, because we have turned off verbose mode):
# piktc -x +C "=hostname; =ll /etc/nologin; echo ''" +H fac
kiev
kiev0
-rw-r--r-- 1 root staff 0 Jul 24 15:47 /etc/nologin
You set (to TRUE) defines with the +D <defines> option, and unset them (to FALSE with -D <defines>. Command-line +D defines and -D undefines override any defines.cfg settings, but #def(ine) and #undef(ine) directives in the config files have the highest precedence overall.
Combining -|+ D switches with +C command strings is perfectly legal (e.g., to toggle the effect of a macro within the command string). (Combining +C with +O, +F or +P is illegal, since you exec +C commands, but you don't exec +O, +F, or +P files. You can't combine exec'ing with file installation or other file management in the same piktc command.)
Using the +E <envar> option, you set the environment variable <envar> (by default to 1). +E <envar>=<value> sets <envar> to <value>. +E <envar> = "<string>" sets <envar> to the character string <string>. (Note the mandatory quote marks, also the spaces around the '=' sign, when assigning a multi-word string.) -E <envar> unsets <envar>. You may unset and set environment variables in the same piktc command, for example:
# piktc ... -E fee fie +E fo fum foo=bar flim = "flam man" ...
(Note that legal environment variable names begin with a letter, followed by any sequence of letters, digits, and/or _ (underscore).)
When specifying alerts/objects/programs, you include items using the "+" option, and exclude using the "-" option. "+A all" includes all alerts. "+A all -A EMERGENCY Info" includes all alerts except EMERGENCY and Info. Another way to achieve the same effect is with just "-A EMERGENCY Info" (leaving out the "+A all", which is implicit).
In piktc commands, 'A' (for alerts) and 'S' (for scripts) are effectively synonymous. You might prefer to use 'A' when processing alerts, and 'S' when processing non-alert scripts.
hosts may refer to operating systems, host aliases, and host groups defined in the systems.cfg file.
"ALL" on the piktc command-line translates to "+A all +S all +P all +F all +O all +H all". So,
# piktc -ierv ALL
will install, enable, and restart everything on all systems. You may combine ALL with the -<A|S|P|F|O> options to exclude certain items. This command, for example, does everything on all systems except the solaris systems:
# piktc -ierv ALL -H solaris
This command reports the status of all alerts except EMERGENCY on all machine except the linux machines:
# piktc -sv ALL -A EMERGENCY -H linux
You may use item macros in your piktc commands, for example
# piktc -iv +F =apacheconf +H webserver
So, in your macros.cfg file (or some appropriate macro #include file), you might have
apacheconf access.conf
httpd.conf
magic
mailman.conf
[and so on...]
The above piktc command would be equivalent to
# piktc -iv +F access.conf httpd.conf magic mailman.conf
[...] +H webserver
In your macros.cfg files, you might define file subsets, including for example
somestuff
somestuff1
somestuff2
[and so on...]
otherstuff
=somestuff
otherstuff1
otherstuff2
[and so on...]
morestuff
morestuff1
morestuff2
[and so on...]
[and so on...]
allstuff =otherstuff // includes =somestuff
=morestuff
[and so on...]
stillmorestuff1
stillmorestuff2
[and so on...]
To update all of your "stuff", you might then use
# piktc -iv +F =allstuff +H [...]
To diff all of your "stuff", except for the "morestuff", you might use
# piktc -fv +F =allstuff -F =morestuff +H [...]
You may use similar macros in your piktc +/-A, +/-O, and +/-P specifications. (Macros are not permitted in +/-H specifications, since you already have the needed functionality by means of host aliases and groups in systems.cfg. Nor are macros allowed in +/-D or any other piktc item specifications.)
Note that by means of command-line item macros, you may effectively alias alert, program, file, and object names (much like you can alias hostnames in systems.cfg).
When piktc launches, it creates a lock file in the =piktdir/etc directory, and removes that file upon completion. The lock file mechanism is to prevent concurrent piktc program runs. In cases of abnormal piktc termination, it will be necessary to manually remove the lock file.
Before shipping a .alt, .obj, or program file to a client, piktc: strips out any // and /* */ comments from the central config file; preprocesses the #if and #ifdef directives in the config file; and performs macro substitutions. In addition, the resultant client-side file loses much of the line and space formatting in the original central config file, and may bear little resemblance to its parent file.
The "f" option suffix tells piktc to "fix" (or "freeze") a file, which leaves all // and /* */ comments in place. (The #fix-#unfix preprocessor directives have a similar effect.) This is especially relevant to programs.cfg, which might possibly include //, /*, and/or */ character sequences. If you choose not to fix a file, you can still include // and /* */ character sequences, but additional backslash escapes may be necessary. (See Regular Expressions.)
Note that the "f" option does not pertain to PIKT #if preprocessing, or to macro substitutions. piktc always honors #if preprocessing directives and macros where present.
Here are the piktc_svc command options:
Usage: piktc_svc [-GhTV]
-G run in debug mode
-h show program help
-T run in test mode
-V show version info
The options operate much the same as for piktc.
piktc_svc is invoked manually, begins at system startup (in the system startup files), or starts using some other service daemon startup utility (See, for example, svcstart.pl in the sample programs.cfg.) piktc_svc does piktc's bidding, handling the actual file installs, alert enablements/disablements, daemon (re)starts, etc. on the client system. Under normal circumstances, while the system is up, piktc_svc never dies.
When piktc_svc launches, it creates a lock file in the =piktdir/etc directory, and removes that file upon completion. The lock file mechanism is to prevent concurrent piktc_svc program runs. In cases of abnormal piktc_svc termination, it will be necessary to manually remove the lock file.
piktc on the master control machine can send requests to piktc_svc on slaves either within the local domain or in different network domains, depending on how you have set up systems.cfg and installed PIKT. If you want to control machines beyond the local domain, you must set the access option in the =piktdir/etc/PIKT.conf file to "global".
PIKT master-slave, client-server communications rely on a four-tier security mechanism involving (1) host authentication, (2) secret key authentication, (3) service access rights, and (4) server-client callback.
When the master piktc wants a slave piktc_svc to do its bidding, the following sequence of events occurs:
-
The master piktc requests an authentication/session key (key) from the slave piktc_svc.
-
The slave piktc_svc generates the authentication/session key (key). It then computes the MD5 checksum of key (keysum). The slave piktc_svc then returns the encrypted key (keyenc) to the master piktc. The pvtkey (private_key set in PIKT.conf and elsewhere) is the symmetric key used for encrypting/decrypting the authentication/session key (keyenc).
-
The master piktc decrypts, using pvtkey, the encrypted key (keyenc), giving it the authentication/session key (key). It, too, computes the MD5 checksum of its copy of the key (keysum). It passes its key's checksum (keysum), along with the service request, back to the slave piktc_svc.
-
The slave piktc_svc does some .rhosts-like authentication checks. If everything passes, it proceeds to the next step, else denies the service.
-
If the master's sent key checksum (keysum) matches the slave's key checksum (keysum), the slave piktc_svc proceeds to the next step, else denies the service.
-
The slave piktc_svc checks to see if the requested service is authorized, and if so proceeds to the next step, else denies the service.
-
The slave piktc_svc does a PIKT-style server-client callback (described below).
-
If everything checks security-wise, the slave piktc_svc fulfills the master piktc's service request, else denies the service.
Diagrammatically, secret key authentication proceeds like this:
MASTER SLAVE
piktc piktc_svc
(1) request key ----------------->
(2) generate key
(3) compute keysum
(4) encrypt key
<----------------------------- (5) return keyenc
(6) decrypt keyenc
(7) compute keysum
(8) send request & keysum ------->
(9) compare two keysums
PIKT callback works as follows: When you issue a piktc command, and if call_back is turned on in PIKT.conf,
-
The slave (remote) host and requested service are registered with the master (local) piktc_svc.
-
The master piktc sends the service request to the slave (remote) piktc_svc.
-
Upon receiving the service request, the slave piktc_svc does a callback back to the master piktc_svc, seeking to verify the request.
-
The master piktc_svc attempts to match the callbacking slave and service request with the locally registered host and service request. It returns the results of the attempted match to the slave piktc_svc.
-
If the slave piktc_svc receives report of a successful match, only then does the slave piktc_svc perform the requested service.
-
The slave piktc_svc returns the outcome of the service request to the requesting piktc.
-
The master piktc_svc deregisters the slave host and requested service.
Diagrammatically, callback proceeds this way:
MASTER SLAVE
piktc <--------------------------------+
| (2) send request |
| (6) return result |
| |
| (1) register slave & request |
| (7) deregister slave & request |
V V
piktc_svc <-----------------------> piktc_svc
(3) callback
(4) match & reply (5) perform service?
The host authentication is always performed. The secret key authentication is (effectively) done only if auth_encryption_type is set to 1 (some number other than 0, for now just 1) in PIKT.conf. Callback is only performed if the call_back parameter is set to ON in the slave PIKT.conf.
In PIKT.conf, if you set data_encryption_type to some number other than 0 (for now, just 1), this will encrypt some data transfers between piktc and piktc_svc. Encrypted data transfers include file installs (piktc -i), file fetches (piktc -f), and command executions (piktc -x). The symmetric encryption key employed for this data encryption/decryption is the "session key" described above.
There is a separate authentication/session key generated and exchanged for each and every service request. So, for example, if you install five files from master to slave, five different authentication/session keys are used.
The private_key doesn't vary unless you change it by, say, substituting a different private_key in PIKT.conf, then installing the revised PIKT.conf on all systems. If you store the private key in an etcdir/private_key file, you would revise and reinstall that file instead. Note that a revised private_key (and any other changed PIKT.conf parameters) won't take effect until you restart all affected piktc_svc, either manually or via 'piktc -R'.
See the PIKT.conf section of this Reference manual for more information.
For more discussion of PIKT's security mechanisms, please refer to the Security Considerations section of this reference.
Every time piktc sends a service request to a client system, this is logged in the =piktdir/var/log/piktc.log file. Likewise, piktc_svc logs, to =piktdir/var/log/piktc_svc.log, every service request it receives. If enabled, callback traffic is logged on both master and slave.
If piktc_svc receives a request from an unauthorized account or system, it flags this as an "ERROR". You can use other log file monitoring Pikt scripts to alert you to this possible security violation. You can also have scripts to analyze and compare the piktc.log and various piktc_svc.log files to verify the validity of service requests.
Don't forget, too, that you can inspect the log files when and if master-slave, piktc-piktc_svc communications go wrong. When debugging master-slave breakdowns, you should run both piktc and piktc_svc in debug (-G) mode. Try, also, setting 'verbose_log' to 'yes' in PIKT.conf (see below).
Here are the piktd command options:
Usage: piktd [-GhTV]
-G run in debug mode
-h show program help
-T run in test mode
-V show version info
piktd, running in debug mode, always outputs error and other messages to the file =piktdir/var/log/piktd.log.
piktd executes in response to a piktc -r, a manual startup, or a system reboot (if you have so configured the system startup files).
When piktd launches, it creates a lock file in the =piktdir/etc directory, and removes that file upon completion. The lock file mechanism is to prevent concurrent piktd program runs. In cases of abnormal piktd termination, it will be necessary to manually remove the lock file.
When piktd starts, it reads the =piktdir/etc/piktd.conf file to find out what alerts are scheduled to run and when, also what mail and print commands are tied to each alert. After reading piktd.conf, piktd writes the file =piktdir/etc/alerts, a simple listing of active alerts. piktc_svc refers to this file when responding to piktc -s requests.
The piktd daemon runs much like cron does. piktd wakes up every minute to check what alerts, if any, are scheduled to run that minute. If an alert is due to run, piktd forks itself, then the child piktd summons the pikt interpreter to run the appropriate scripts. When pikt is finished, the child piktd dies. Meanwhile, the parent piktd goes on to consider other alerts, then sleeps until the next minute comes around. The parent piktd only dies when killed manually, via a piktc -k or -r, through a system reboot, when it encounters an unrecoverable problem (these are logged automatically), else through a simple program crash (due to a bug, for example).
pikt is the Pikt script interpreter. It takes the following command-line arguments:
Usage: pikt [-cGhTV] [+M "<mailcmd>"] [+L "<lpcmd>"] [+C "<cmd>"]
[+A|S <alert/script>]
-c syntax check alarm script file
-G run in debug mode
-h show program help
-T run in test mode
-V show version info
+C pikt command
+M mail command
+L print command
+A|S alert/script
The -c option forces a syntax check. Before .alt, .obj, and program files are installed on the clients, piktc syntax checks the central .cfg files for errors. piktc catches most, but not all, syntax errors. It does not check, for example, if a script uses a reserved function name as a variable. pikt, on the other hand, does a thorough check of client-side config file syntax, and some semantic checking as well. It will catch many errors that piktc misses (including the one cited above), but it will not detect all possible errors. It will not determine whether a function has the appropriate number and type of function arguments, which is only detected at run time. (We will be extending the pikt syntax checks in the future.) (There is, in fact, another pikt command option: -C. This is for when piktc calls pikt to do a syntax doublecheck. All -C does is to tell the invoked pikt to look in the piktc staging directory for the checked files; the pikt syntax check is the same Thus, it makes no sense to do a "pikt -C" on a slave system. "pikt -C" is really reserved for piktc's use.)
The -G option turns on debugging. When run interactively, pikt sends debug messages to stderr. When invoked via piktd, pikt outputs debug messages to =piktdir/var/log/<alert>.log.
If an .alt file fails a syntax/partial-semantics check, pikt logs the error, then dies. (You may use other Pikt scripts to check the pikt alert logs for such errors.) During a pikt run, other semantic errors might cause a particular alarm script to abort (with such errors also logged), but the pikt session doesn't die; the rest of the alarm scripts still run. These error logs, especially when combined with Pikt scripts combing the log files for error statements, are extremely useful in determining the cause of breakdowns.
The -h option shows program help (shown above).
The -T runs piktc in test mode. You ordinarily wouldn't do this outside the installation 'make check'.
The +C option allows you to run Pikt command sequences at the command line. For example,
vienna# pikt +C 'output $checksum(4,"/usr/bin/login")'
c03df7329470a15e7312a7f48d12217a 29292 /usr/bin/login
Another example:
vienna# pikt +C 'output $groupmembers("adm")'
root,adm,daemon
You might use this feature to access Pikt functions from within programs written in other scripting languages, e.g.,
$today = `pikt +C 'output \$dayname()'`;
Perhaps more importantly, 'piktc +C' allows you to do some interesting things with your PIKT config files. (See #exec, #piktexec, #pexec.)
The +M option precedes a quoted string specifying the mail command (and subject and recipients) to be used with the current alert. The +M and mail command are optional.
The +L option precedes a quoted string specifying the print command (and printer) to be used with the current alert. This, too, is optional (if no alarms output to a printer).
If neither mail nor print commands are specified, pikt outputs to stdout. In this way, you may run Pikt scripts at the command line. This is especially useful when developing and debugging Pikt scripts.
The +A option precedes an unquoted alert identifier. <alert> is not the name or path of a .alt file (e.g., /pikt/lib/alerts/Urgent.alt); it is the name of the alert as given in the alerts.cfg file (e.g., Urgent).
In pikt commands, 'A' (for alerts) and 'S' (for scripts) are effectively synonymous. You might prefer to use 'A' when processing alerts, and 'S' when processing non-alert scripts.
When a pikt session starts, it writes a lock file, for example, "Urgent.lock", in the =piktdir/etc directory. This is to prevent concurrent pikt runs for the same alert. pikt removes this lock file on script completion. When and if pikt dies unnaturally, you will have to remove the <alert>.lock file manually.
When a Pikt script does an 'exec wait', it writes a lock file for that script in the =piktdir/etc directory. The lock file contains the command string being exec'ed. If an alert hangs or becomes blocked, inspecting an exec wait lock file can sometimes explain the blockage.
pikt dies a natural death after processing all current alert scripts. You can force pikt to die prematurely by use of the "die" command within a Pikt script.
pikt logs all warnings and errors to the current alert's log file. When run interactively (without the +M or +L options), pikt also logs to the current alert's log file.
pikts is the PIKT comment-stripping utility. It takes the following command-line arguments:
Usage: pikts [-bGhlTV]
-b strip away block comments only
-G run in debug mode
-h show program help
-l strip away line comments only
-T run in test mode
-V show version info
note: the default is to strip away both block and line comments
(Currently, the '-G' & '-T' options have no real effect. They are there just for consistency.)
pikts is useful for stripping away PIKT-style comments (block /* */ and/or line // comments), leaving everything else including #-style preprocessor directives, from PIKT config files. You might use it, for example, when autogenerating other auxiliary (#include'd) config files as follows:
set $lines[#j] = $command("=pikts < =cfgdir/macros/files_pikt_" .
$[#j] . "_macros.cfg | =getidents")
In this Pikt script line, $command() pipes a macros config file through the pikts filter and onto the =getidents program.
Pikt scripts can invoke pikts, as can scripts written in Perl, Python, Awk, or any other language. You can also invoke it at the Unix command line, if you wish.
See the sample config files for demonstrations of config file autogeneration.
piktx is the PIKT remote command execution utility. It takes the following command-line arguments:
Usage: piktx <-xXvhGV>
+C <command(s)>
+|-H all|<host(s)>
-x execute alert(s)/script(s)
-X execute alert(s)/script(s) with no wait
-v run in verbose mode
-h show program help
-G run in debug mode
-V show version info
+C <command(s)> include command string(s)
+|-H all|<host(s)> include/exclude host(s)/os(es)/group(s)/
alias(es)
Why use piktx instead of piktc for remote command execution? For the following reasons:
-
piktc runs on the master system only (for most operations, including remote command execution). piktx will run on any PIKT system, master or slave.
-
piktc does not allow multiple, concurrent program runs (except for some auxiliary operations, for example 'piktc -L' or 'piktc -M'). With piktx, more than one simultaneous run is possible. (With piktc, if one sysadmin has launched a piktc operation, this effectively blocks other sysadmins from doing the same. With piktx, there is no blocking.)
-
piktx uses ssh (or, if you prefer, rsh; to enable this, you need to hand-edit the piktx code) to handle the actual remote command execution. piktc uses the piktc-to-piktc_svc network transport.
In order for piktx to be useful on slave systems, you must install a limited set of .cfg files in the cfgdir on those systems. Typically, these files would include just systems.cfg (and perhaps a systems subdirectory), macros.cfg (and perhaps a macros subdirectory), and maybe defines.cfg (and perhaps a defines subdirectory). See the sample files.cfg for how to set this up. You would install the .cfg files to the slave systems with the usual 'piktc -iv +F all +H ...'. In your files.cfg setup, be sure to place a '#if ! piktmaster ... #endif' wrapper around the installable .cfg files so as not to inadvertently clobber your master's .cfg files!
Unlike many of the other PIKT binaries (which are written using a combination of C, lex, and yacc), piktx (like piktf, pikth & rkey) is written in Perl.
pikth is the PIKT on-line help utility. It takes the following command-line arguments:
Usage: pikth [options] [-i value]
Options:
-i search for error code 'value' (text or ID)
-V show version
-G debug mode
-h help
Suppose, for example, you run piktc and get the following error:
Oct 14 09:07:18 vienna piktc[20916]: [ID 1101 ERROR]
(../../../src/piktc/bitset.c, line 223, getbs())
/pikt/lib/configs/macros.cfg, at or near line 489:
define strict unknown
You could get additional explanation by using pikth with the indicated numerical error id:
# pikth -i 1101
Error #1101 (ERRID_DEFINE_UNKNOWN)
The referenced logical define is unknown (does not appear to be registered
in your defines.cfg file).
This is always a fatal error.
Please
--change the reference (by fixing a misspelling maybe)
--remove the reference (remove the #ifdef stanza)
--or add the referenced logical define to your defines.cfg file
--refer to the defines.cfg section of the Reference for further
explanation
pikth gives an extended explanation for the error, suggests possible causes and fixes, and directs you to the appropriate place(s) in the documentation for further reference.
You would see the same the same explanation if instead you were to specify the named error id:
# pikth -i ERRID_DEFINE_UNKNOWN
Error #1101 (ERRID_DEFINE_UNKNOWN)
The referenced logical define is unknown (does not appear to be registered
...
pikth is a continual work-in-progress. Eventually, the design goal is for pikth to point you to a solution for 99%+ of your PIKT problems. (Note that pikth provides on-line help for the PIKT C binaries only--piktc, piktc_svc, pikt, piktd, and pikts--and not for the Perl utilities--piktx, piktf, rkey, and pikth itself.)
Unlike many of the other PIKT binaries (which are written using a combination of C, lex, and yacc), pikth (like piktf, piktx & rkey) is written in Perl.
piktf is a utility for finding elements within the PIKT configuration. It takes the following command-line arguments:
Usage: piktf [options] [<regexp>]
Options:
-i do case insensitive matches
-l do literal matches, ignoring special regexp chars
-f list only matching .cfg, .alt, .obj, or prgdir files
-C list only files in the configs directory
-c print count of matching lines
-n print line number of matching lines
-p match filenames, not files content
-V show version
-G debug mode
-T test mode
-h help
note : with -n, all matches are reported for a file.
without -n, matching files are reported once.
-n, -c and -p are mutually exclusive.
The -i option says to do case-insensitive matches on the given regular expression.
The -l option does literal matches, suppressing the special effect of characters such as *, +, ., and so on.
The -f option shows only the "official" PIKT configuration files ending with the .cfg, .alt, or .obj extensions, also any files in the programs directory (where there is no way we can predict file extensions, if any). The -f option has the effect, therefore, of not showing files with extensions such as, .bak, .piktbak, and ~ (Emacs backup files), for example.
The -C option lists only files in the PIKT configs directory, thereby excluding files in the alerts, objects, programs, and other directories. The -C option will therefore only tend to show .cfg files.
The -c option will print the files containing the <regexp>, also the total count of matching lines.
The -n option will print the files containing the <regexp>, also the line numbers of matching lines.
The -p option will search for <regexp> among the file names, not within the files themselves.
The -V option shows the version number.
Currently, the '-G' & '-T' options have no real effect. They are there just for consistency.
The -h option shows program help (shown above).
piktf is especially useful if your PIKT setup is big and complex, and you have modularized your PIKT setup into many different #include files scattered among many different subdirectories.
Unlike many of the other PIKT binaries (which are written using a combination of C, lex, and yacc), piktf (like pikth, piktx & rkey) is written in Perl.
rkey is the PIKT keys.conf generation utility. It takes the following command-line arguments:
Usage: rkey [options] [+H hosts -H hosts ...]
Options:
-u[uid] uid generation
-g[gid] gid generation
-k[key] key generation
-l length key length
-a equivalent for -u -g -k
-Q displays the randomness Quality evaluation
-v be verbose
-V show version
-G debug mode
-h help
'+H hosts -H hosts' are like their piktc and piktx counterparts with one exception: It is possible to specify a host not registered in your systems.cfg. Indeed, it's even possible to run rkey without any systems.cfg at all!
-u[uid] specifies that rkey should generate a random uid field. If an integer is specified, no random generation will take place and that integer will be used instead. The uid is limited to the range from 0 to 2^31 - 1 (2,147,483,647).
-g[gid] specifies that rkey should generate a random gid field. If an integer is specified, no random generation will take place and that integer will be used instead. The gid is limited to the range from 0 to 2^31 - 1 (2,147,483,647).
-k[key] specifies that rkey should generate a random key. If a string is specified, no random generation will take place and that string will be used as the key instead.
-l length is the length of the random key in chars. The key length must be at least 16. The maximum key size is currently 56 chars, due to a BlowFish limitation. (BlowFish is currently the only PIKT-supported cipher.)
-a is a shortcut for -u -g -k, i.e. when you want to generate lines with the hostname, uid, gid, and key.
-Q displays the quality rating. This rating's purpose is to evaluate the randomness generation quality given the current environment. The results range from 0 to 6, where 0 it the worst and 6 the best achievable rating. The method used to calculate the rating is really simple, and is influenced by pseudo-random devices availability (/dev/urandom, for example), source lists, and installed modules.
-v gives a verbose display, and is especially useful with -Q.
-V shows the current version number.
-G activates debug mode. This can help you locate which randomness sources succeed, and which don't.
-h outputs the help and usage display. Using -v with -h gives detailed options help.
Unlike the other PIKT binaries (which are written using a combination of C, lex, and yacc), rkey (like piktf, pikth & piktx) is written in Perl.
See the keys.conf section of this Reference for more information.
Each time one of the PIKT binaries (piktc, piktc_svc, pikt, piktd, or pikts) starts up, it looks for the PIKT configuration file, PIKT.conf, in =piktdir/etc. If it fails to find =piktdir/etc/PIKT.conf, it looks for /etc/PIKT.conf, then /etc/pikt/PIKT.conf, then /usr/local/etc/PIKT.conf, and finally /usr/local/etc/pikt/PIKT.conf. If it doesn't find PIKT.conf in any of those places, the program will abort.
Here is the format for the PIKT.conf file:
uid <uid> [0, or use any random integer]
[gid <uid>] [0, or use any random integer]
master <domainname> [fully-qualified domain name
of master control machine,
e.g., "vienna.uppity.edu"]
domain <domain> [domain of master control machine,
e.g., "uppity.edu"]
access <local|global>
[authenticate_by_master <yes|YES|on|ON|true|TRUE|
no|NO|off|OFF|false|FALSE>]
[defaults to 'yes']
[master_address <ipaddr>] [the ip address of the
master control machine]
[authenticate_by_master_address <yes|YES|on|ON|true|TRUE|
no|NO|off|OFF|false|FALSE>]
[defaults to 'no']
[master_ethernet_address <ethernet_addr>]
[the ethernet address of the
master control machine]
[authenticate_by_master_ethernet_address <yes|YES|on|ON|true|TRUE|
no|NO|off|OFF|false|FALSE>]
[defaults to 'no']
[auth_encryption_type <0|1>] [0 is none (default), 1 is blowfish]
[data_encryption_type <0|1>] [0 is none (default), 1 is blowfish]
[private_key <key>] [private symmetric encryption key
e.g., "what's up, doc?";
also: pvtkey]
[homdir <home directory>]
[bindir <bin directory>]
[etcdir <etc directory>]
[lokdir <lock file directory>]
[libdir <lib directory>]
[vardir <var directory>]
[altdir <alerts directory>]
[prgdir <programs directory>]
[objdir <objects directory>]
[cfgdir <configs directory>]
[hstdir <histories directory>]
[logdir <log directory>]
[arpcmd <arp command path>]
[catcmd <cat command path>]
[cksumcmd <cksum command path>]
[cpcmd <cp command path>]
[diffcmd <diff command path>]
[echocmd <echo command path>]
[egrepcmd <egrep command path>]
[filecmd <file command path>]
[nicecmd <nice command path>]
[pscmd <ps command path>]
[rmcmd <rm command path>]
[rpcinfocmd <rpcinfo command path>]
[scpcmd <scp command path>]
[sumcmd <sum command path>]
[tailcmd <tail command path>]
[trcmd <tr command path>]
[call_back <yes|YES|on|ON|true|TRUE|no|NO|off|OFF|false|FALSE>]
[call_back defaults to 'yes']
[<service> <yes|YES|on|ON|true|TRUE|no|NO|off|OFF|false|FALSE>]
...
[all services default to 'yes']
[tcp_only <yes|YES|on|ON|true|TRUE|no|NO|off|OFF|false|FALSE>]
[tcp_only defaults to 'no']
[restart_piktc_svc_wait <seconds>] [number of seconds piktc will wait
before verifying actual piktc_svc
restart; the default is 5]
[rpc_timeout <seconds>] [number of seconds piktc will wait
for reply on a piktc -x (execute)
request before timing out if no
reply from the client;
the default is 60]
[rpc_retry_timeout <seconds>] [number of seconds piktc will wait
for reply on a piktc -x (execute)
request before retrying the
request if no reply from the
client; the default is 120,
which turns off retry, in effect]
[rpcinfo_retries <# retries>] [the number of times piktc
retries establishing contact
with a remote piktc_svc; the
default is 1 retry, i.e., two
attempts maximum]
[execcmdout_limit <# chars>] [number of characters returned by a
'piktc -x +C' command; the default
is 1000000 characters per client]
[fork_delay <seconds>] [the number of seconds a
parent process will delay
after forking a child process;
the default is 1]
[verbose_log <yes|YES|on|ON|true|TRUE|no|NO|off|OFF|false|FALSE>]
[verbose_log defaults to 'no']
[auto_syslog <yes|YES|on|ON|true|TRUE|no|NO|off|OFF|false|FALSE>]
[auto_syslog defaults to 'no']
[syslog_facility [0-7]] [correspond to local0 through
local7; default is 0 for local0]
[sort_messages <yes|YES|on|ON|true|TRUE|no|NO|off|OFF|false|FALSE>]
[sort_messages defaults to 'yes']
[debug <yes|YES|on|ON|true|TRUE|no|NO|off|OFF|false|FALSE>]
[debug defaults to 'no']
The four parameters--uid, master, domain & access--are all required. All other PIKT.conf parameters are optional.
The uid & gid have no role outside of master-slave authentication. We suggest that you set the PIKT.conf uid, and optionally the gid, to some arbitrary, random, and secret integer(s), thereby achieving a measure of "security through obscurity".
For example, in all systems' PIKT.conf, you could set
uid 491158200
gid 283617116
and both the master and slave(s) will compare these numbers when authenticating. (That is, if the slave's uid and gid don't match the calling master's uid and gid, the service request is denied.)
By default, piktc_svc authenticates client requests by master name. By adding 'authenticate_by_master_address yes' and 'master_address <ipaddr>', you tell piktc_svc to check the IP address of the requesting client (the master system) before acceding to the request. The default is no authentication by master address. One or both of authenticate_by_master and authenticate_by_master_address can be 'yes', but both cannot be 'no'. These authentication parameters provide another security option as well as another thing to tweak in troublesome authentication situations (involving DNS and/or NIS problems).
If you add the following optional settings to PIKT.conf
master_ethernet_address 11:22:33:44:55:66
authenticate_by_master_ethernet_address TRUE
the PIKT slave will do an 'arp <piktmaster>' lookup of the piktmaster's MAC/ethernet address. Unless the returned address matches the address set in PIKT.conf, the service request is denied.
We make the recommendation, also, that you hard-code the piktmaster's MAC/ethernet address on each slave, either by registering this in /etc/ethers or by running the command
arp -s <piktmaster> <piktmaster's ethernet address>
in the appropriate system startup file.
(If you register the piktmaster's ethernet address in /etc/ethers, consider managing this file in files.cfg.)
These steps will only bolster security for slaves sharing the same network segment as the piktmaster. (For slaves on a different network segment, they will not know the piktmaster's MAC address, of course. Issuing the above arp command on such systems will yield the results "no entry", "unavailable", or some equivalent.) For slave systems on separate network segments, you must be sure to set
authenticate_by_master_ethernet_address FALSE
or leave that out of their PIKT.conf files entirely. (The setting defaults to FALSE.)
If you manage your site's PIKT.conf from within files.cfg, you could do something like this:
#if local
master_ethernet_address 11:22:33:44:55:66
authenticate_by_master_ethernet_address TRUE
#else
authenticate_by_master_ethernet_address FALSE
#endif
where 'local' is a hostgroup defined in your systems.cfg. You could set these systems by hand, but a better way would be to do it dynamically like this
local
members
#verbatim <systems/local_systems.cfg> [/pikt/bin/piktc -xI +C
"/sbin/ifconfig -a | /usr/bin/grep 121.212.123 >/dev/null &&
/bin/hostname" -H downsys 2>/dev/null]
if, for example, 121.212.123 identifies your piktmaster's subnet.
Different network topologies or arrangements would require different approaches. How you handle this is your call.
For greater security, consider managing PIKT slaves from piktmaster machines on the same network segment only. (It would be possible to have an uber-piktmaster push .cfg files to lower ranking piktmaster machines, one for each separate network segment. That's a topic too advanced for the current discussion, however.)
Note that ARP authentication will not defeat a very skilled, experienced cracker. It does provide an extra thin layer of security (and complexity), however, and may be worthwhile using in many situations.
By default, PIKT's key-keyenc-keysum authentication scheme is turned off. However, if you add to PIKT.conf
auth_encryption_type 1 // 1 is blowfish, 0 is no encryption (default)
this will activate the authentication sequence described in piktc_svc, also in Security Considerations.
(The .rhosts-like authentication is always done. callback is done unless you have set the call_back parameter to NO on the slaves.)
By default, data transfers between piktc and piktc_svc are not encrypted. However, if you add to PIKT.conf
data_encryption_type 1 // 1 is blowfish, 0 is no encryption (default)
this will activate encryption. (0 signifies the default, no encryption.)
Encrypted data transfers include file installs (piktc -i), file fetches (piktc -f), and command executions (piktc -x). The symmetric key employed for this encryption/decryption is the "session key" generated whenever piktc requests a service from piktc_svc.
If you set data_encryption_type to 1 (non-zero), you should also set auth_encryption_type to 1 (non-zero). It makes little sense to set data_encryption_type to 1 but auth_encryption_type to 0. You may set both to 0 if you want to skip encryption altogether (or when encountering difficulties).
For now, Blowfish is used both for encrypting/decrypting the authentication/session key as well as for encrypting/decrypting data transfers. (We intend to make additional ciphers available in the future.)
By default, the private symmetric encryption key, pvtkey, is set to PVTKEY, defined by default in src/config.h as "CHANGE_ME". You can override this either by editing src/config.h before doing the 'make' or by specifying '--with-private-key=FOO' when doing 'configure'. PVTKEY is compiled into the binaries.
You can override PVTKEY in one of two ways:
-
By specifying a private_key (or pvtkey) string in PIKT.conf.
-
Or by specifying a key string in a PIKT etcdir/private_key file.
The etcdir/private_key string takes precedence over any private_key set in PIKT.conf; and either will override the PVTKEY compiled into the binaries.
In PIKT.conf, you can set private_key (aka pvtkey) this way
private_key thisisatest
or this way
private_key "this is a test"
that is, as a sequence of characters, none of which may be space or tab, or as a (double) quoted string, which may include spaces and/or tabs.
Your private_key (or pvtkey, or PVTKEY) must not exceed 56 characters in length. (This is a Blowfish limitation.)
In order for a master piktc (and piktc_svc, when doing callback) to coordinate properly with a slave piktc_svc, all private_key (or pvtkey or PVTKEY) settings must be in agreement, as must auth_encryption_type and data_encryption_type.
It is vitally important to keep secret these and other settings in PIKT.conf (also etcdir/private_key, if you prefer that option)! You should ensure 640 or perhaps 600 or 400 permissions for PIKT.conf (and etcdir/private_key), and secure the permissions on the etcdir directory (where PIKT.conf resides) and all of its parent directories as well.
When you need to update your PIKT.conf files with a revised private_key (or if you store the key in a stand-alone etcdir/private_key file), use scp or some other secure method for distributing those files. Once you have the private_key established and PIKT encryption activated everywhere, you may of course manage secure installation of your PIKT.conf and/or etcdir/private_key like you would any other system file by way of, e.g., 'piktc -i +F PIKT.conf' or 'piktc -i +F private_key'. Note that the new private_key won't take effect until you restart the piktc_svc daemons, either manually or via 'piktc -R'.
If a PIKT binary is invoked as, e.g., <path>/bin/pikt, <path> is assumed to be the PIKT home directory by default. (If the binary were invoked as simply, e.g., 'pikt', then the program searches through the PATH environment variable to determine <path>.) You can override this home directory default location by setting homdir to something else (e.g., '/usr/lib/pikt').
Having determined the PIKT home directory (<path>, aka '=piktdir'), the PIKT binary expects to find certain essential directories in the following default locations
-
<path>/bin
-
<path>/etc
-
<path>/lib
-
<path>/lib/alerts
-
<path>/lib/programs
-
<path>/lib/objects
-
<path>/lib/configs
-
<path>/var
-
<path>/var/histories
-
<path>/var/log
You can override any of these locations with the parameters: bindir, etcdir, lokdir, libdir, altdir, prgdir, objdir, cfgdir, vardir, hstdir, logdir.
When the PIKT binaries are compiled, several UNIX command paths are hard-coded in. This would normally make it difficult to impossible to take binaries compiled on one system and use them on another with different command paths. (It is of course impossible to take binaries compiled on one OS and use them on another.) You may use the arpcmd, cksumcmd, ..., trcmd settings to override the hard-coded command paths as a workaround to this problem.
If call_back is set to 'no', then service-to-client, pikt_svc-to-piktc_svc callback is disabled. For greater security, 'call_back yes' is the default. If callback breaks under unusual circumstances, consider setting call_back to 'no'.
(callback is not currently supported on AIX, Digital UNIX, HP-UX, IRIX, or SCO OpenServer systems. If your master system is an AIX, Digital UNIX, HP-UX, IRIX, or SCO OpenServer system, and if you have slave systems other than those types, then you will have to set call_back to 'no' on those slaves. The call_back parameter is ignored on AIX, Digital UNIX, HP-UX, IRIX, and SCO OpenServer.)
The available services are:
all_services ['yes' is the default; applies to all
services listed below]
kill_service [applies to both piktd & piktc_svc]
kill_piktd_service
kill_piktc_svc_service
restart_service [applies to both piktd & piktc_svc]
restart_piktd_service
restart_piktc_svc_service
execute_service
execute_commands_service [needed for fetch services]
execute_alerts_service [or: execute_scripts_service]
disable_alerts_service
enable_alerts_service
show_alerts_status_service
install_service [for alerts/scripts/programs/files/objects]
install_alerts_service [or: install_scripts_service]
install_programs_service
install_files_service
install_objects_service
fetch_service [for alerts/scripts/programs/files/objects]
fetch_alerts_service [or: fetch_scripts_service]
fetch_programs_service
fetch_files_service
fetch_objects_service
cksum_service [for alerts/scripts/programs/files/objects]
cksum_alerts_service [or: cksum_scripts_service]
cksum_programs_service
cksum_files_service
cksum_objects_service
delete_service [for alerts/scripts/programs/files/objects]
delete_alerts_service [or: delete_scripts_service]
delete_programs_service
delete_files_service
delete_objects_service
list_service [for alerts/scripts/programs/files/objects]
list_alerts_service [or: list_scripts_service]
list_programs_service
list_files_service
list_objects_service
The 'tcp_only' parameter has many of the piktc server calls switch from their default UDP transport to a (possibly) more secure and more reliable TCP transport. This setting might also help solve some possible firewalling difficulties. Paradoxically, it seems to speed up certain forms of piktc-to-piktc_svc communications. Try setting tcp_only to TRUE if you are experiencing timeouts when attempting to connect to slave systems over slow or troublesome network connections.
The 'restart_piktc_svc_wait' parameter specifies how many seconds piktc, when doing a restart_piktc_svc (piktc -R), waits before rechecking the slave's piktc_svc pid in order to verify actual restart. You might need to set this to a higher figure for particularly slow slave systems (thereby giving them extra time to spawn the substitute piktc_svc before the master's verification check).
The 'rpc_timeout' parameter tells piktc how long to wait (in seconds) for a reply after sending a -x, execute script, request to a client. If you set this figure too low, piktc will erroneously infer failure if the executing script (or scripts) is (are) long and complicated. If you set rpc_timeout too high, piktc may be kept waiting too long in cases of actual client-side piktc_svc failure (i.e., when piktc_svc is not running on the client). By default, rpc_timeout is set to 60 seconds, 1 minute, which should give enough time for lengthy scripts to complete without blocking piktc too long in situations of actual timeout. Adjust this parameter as necessary.
The 'rpc_retry_timeout' parameter tells piktc how long to wait (in seconds) for a reply after sending a -x, execute script, request before retrying the request when no response comes from the client. Under normal circumstances, you should never set this below rpc_timeout, for then you risk executing the script(s) twice or more on the client. By default, rpc_retry_timeout is set to twice the default rpc_timeout (120 and 60 seconds, respectively). Under unusual circumstances, you might want to set rpc_retry_timeout below rpc_timeout. Adjust as necessary.
The 'rpcinfo_retries' parameter tells piktc how many times to retry connecting to a remote piktc_svc. The default is one retry--e.g., as many as two attempts as needed. This parameter is useful when slow network connections cause piktc to infer that the remote piktc_svc is down when it is, in fact, up. Set rpcinfo_retries to 2 or higher for really slow networks or slow remote systems.
rpc_timeout, rpc_retry_timeout, and rpcinfo_retries only need be set, if at all, in the master control machine's PIKT.conf file.
By default, a 'piktc -x +C' command will output to screen a maximum of 1,000,000 characters per client (i.e., per each host in the +H set). You can set this to a lower or higher number using the execcmdout_limit parameter.
When a parent process forks a child process, it might need to wait for that child process to do something first. The best way to handle this delay is for the parent to wait for some signal from the child. At several places in the PIKT code, however, it is difficult or impossible to do it this way, so we just have the parent process wait an arbitrary time instead. By default, these parent processes will wait 1 second. If you experience odd program behaviors (e.g., unexplained program hangs), you might try upping fork_delay to 2 or more. In some OSes, you might be able to reduce fork_delay to 0 and thereby achieve faster performance.
By default, verbose_log is set to 'no'. You can activate a greater number of (less important) log messages by setting this to 'yes'.
By default, messages are sent to the syslog facility by means of 'output syslog' statements within Pikt scripts. You can, additionally, send all program outputs, and all log messages (e.g., log messages ordinarily sent just to piktc_svc.log, <alert>.log, etc.), to syslog by setting the auto_syslog parameter to 'yes'. This is especially useful if you send all such syslog messages to a central log host for further processing (for example, translating into some sort of graphical display), or just to centrally archive all PIKT-related messages.
If auto_syslog is set to 'yes', all PIKT messages are sent to the local0 facility by default. You can override this default by setting the syslog_facility parameter to a number between 0 and 7 (corresponding to local0 through local7).
In alert messages, alarms are sorted by severity levels, from "emergency" (highest) to "debug" (lowest). If for some reason you prefer that the alarm order you specify in the alerts.cfg listing determines the order of alarm output, you may override the default by means of the sort_messages setting (setting it to 'no').
If you set debug to 'yes' (the default is 'no'), all PIKT programs will run as if you had invoked them with the -G (debuG) command-line switch.
You may use ordinary PIKT-style // comments within PIKT.conf ('#' also serves as a commenting character in this file).
For authentication purposes (and among other authentication methods), PIKT uses the PIKT.conf settings uid, gid, and private_key, for example (from a sample PIKT.conf):
uid 3817379002 // defaults to 0
gid 7117260626 // defaults to 0
...
private_key "8z0 9234bvd; lkjn!z-ne0)s@@5" // defaults to "CHANGE_ME"
What if uid, gid, and private_key were common across your PIKT domain? If one managed to crack any system in that domain, one would have access to all common secrets.
To solve this problem, you may use per-slave uid, gid, and private_key settings.
On the piktmaster, these settings are activated by the presence in the etcdir (the directory where PIKT.conf resides) of the file keys.conf. Your etcdir/keys.conf file might look something like the following:
// host uid gid private_key
vienna 334292319 963813343 "23gb-[098425ybdbfz;lo3q4"
nantes 343343411 1043232633 "P)(Q#Rbgf;jl334;ljbq2345;jl"
berlin 1001239167 1009006239 "234ag-09__)(*lkj324bn;ljfg"
...
With those settings, vienna's PIKT.conf must have
uid 334292319
gid 963813343
...
private_key "23gb-[098425ybdbfz;lo3q4"
nantes' PIKT.conf must have
uid 343343411
gid 1043232633
...
private_key "P)(Q#Rbgf;jl334;ljbq2345;jl"
and so on for every other host registered in the piktmaster's systems.cfg.
Then, the piktmaster piktc will use the vienna keys when communicating with vienna's piktc_svc, the nantes keys when communicating with the nantes piktc_svc, and so on. If there is any mismatch between a slave's PIKT.conf uid, gid, and private_key and their corresponding values registered in the piktmaster keys.conf, authentication will fail, and the requested service will be denied.
How does one get the keys out to each slave PIKT.conf? One way to do it is to open up a secure session to the slave (using ssh most likely), and hand-edit in that slave's uid, gid, and private_key.
But, with PIKT, there is a much better way.
First off, you should manage your PIKT.conf files from the central PIKT configuration. In your piktmaster files.cfg, you should have the directive
#include <files/pikt_conf_files.cfg>
Your files/pikt_conf_files.cfg should look as follows:
/////////////////////////////////////////////////////////////////////////////
PIKT.conf path "/pikt/etc/PIKT.conf" mode 640 uid 0 gid 0
#fix
/////////////////////////////////////////////////////////////////////
// general piktc-to-piktc_svc access parameters
// these are all required
//uid 0
#unfix
uid =piktuid
gid =piktgid
#fix
master vienna.uppity.edu
domain uppity.edu
access local // access may be "local" or "global"
...
data_encryption_type 1 // blowfish
auth_encryption_type 1 // blowfish
#unfix
private_key =piktprivate_key
#fix
/////////////////////////////////////////////////////////////////////
#unfix
/////////////////////////////////////////////////////////////////////////////
=piktuid, =piktgid, and =piktprivate_key are pre-defined, built-in macros, much like =piktdir, =pikthostname, etc. =piktuid resolves to the uid setting for the current host. So for example, if piktc were installing PIKT.conf to vienna, =piktuid would resolve to 334292319, =piktgid would resolve to 963813343, and =piktprivate_key would resolve to "23gb-[098425ybdbfz;lo3q4". As piktc turns its attention to installing PIKT.conf to different systems, the macro resolutions would resolve differently, based on the keys.conf settings, for each different system.
There is a gotcha when installing PIKT.conf from files/pikt_conf_files.cfg. If vienna has the indicated uid, gid, and private_key settings in its PIKT.conf, if you change those settings to something else in the piktmaster keys.conf, you have introduced a mismatch, service will be denied, and your 'piktc -iv +F PIKT.conf +H vienna' operation will fail. What to do?
You may make use of a special piktc option, -p for "install PIKT.conf", to solve this problem. 'piktc -p' bypasses the usual PIKT install mechanism to rely instead on scp (the "secure copy" program distributed with Ssh or OpenSsh) and piktx, which itself relies internally on ssh.
If you issue the command 'piktc -pv +H vienna', you would see this:
processing vienna...
killing daemon (piktc_svc)...
installing PIKT.conf...
PIKT.conf installed
restarting daemon (piktc_svc)...
determining piktc_svc pid...
daemon (re)started
Behind the scenes, piktc:
-
invokes piktx to kill the running piktc_svc (if any) on the slave
-
invokes piktx, which invokes scp to install the revised PIKT.conf on the slave
-
invokes piktx to set the proper ownerships and permissions on the newly installed PIKT.conf
-
invokes piktx to (re)start piktc_svc on the slave
-
checks the piktc_svc pid, to see if the (re)start was successful
To update the keys for a single system, say vienna, you would edit its line in keys.conf, then push the revised PIKT.conf out to vienna with the command 'piktc -pv +H vienna'. 'piktc -pv +H all' (or perhaps 'piktc -pv -H downsys') would push updated PIKT.conf files to all systems. 'piktc -p' takes as much as a minute or two per system, so updating keys across all systems is not something you'll want to do often.
In order for this all to work, you MUST
If you haven't done the setup correctly, your results are uncertain. Most likely your 'piktc -p' will fail.
For each host in keys.conf, you may
-
list the uid, gid, and private_key
-
list just the uid and gid
-
list just the private_key
-
omit the host entirely
-
mention the hosts more than once, in which case the values set last are the ones that apply.
For example, these are all legitimate keys.conf settings.
vienna 334292319 963813343 "23gb-[098425ybdbfz;lo3q4"
nantes 343343411 1043232633
berlin "234ag-09__)(*lkj324bn;ljfg"
nantes 898573211 483450870
...
nantes "vb-05xf%-r0s* #$%^ 88vw-bs"
For any missing settings, they default to the piktmaster's values.
In this example, assume that vienna is the piktmaster. (There is no need for the piktmaster to go first. It could go anywhere in the keys.conf file. If the piktmaster were missing entirely from the keys.conf file, its settings would be those established in its PIKT.conf file.)
If there was only one berlin line as shown, its uid-gid-private_key settings would be
334292319 963813343 "234ag-09__)(*lkj324bn;ljfg"
If the nantes settings were specified as above, its resultant settings would be
898573211 483450870 "vb-05xf%-r0s* #$%^ 88vw-bs"
In other words, it's not a grievous mistake to omit a host from the keys.conf file. The host(s) will assume the uid, gid, and private_key of the piktmaster. It's not terribly bad to omit the piktmaster, since it (and any missing hosts) will assume the uid, gid, and private_key from its (the piktmaster's) existing PIKT.conf file. Nor is it bad (but it would be confusing!) to list a host more than once in keys.conf. The last listed values will apply.
Note that one implication of this flexibility is that you could have a keys.conf file with private_key settings only, leaving out any uid-gid settings (in which case the uid-gid settings would default to those in the piktmaster's PIKT.conf).
It goes without saying that keys.conf should be on the piktmaster only (in its etcdir). Do not manage your keys.conf as you would PIKT manage other files (in files.cfg), for then you might mistakenly install your keys.conf file onto one or all of the slave systems!
There is a PIKT utility, rkey, for generating keys.conf entries, or that file in its entirety. See rkey for more details.
|