From 7d4c6eaf13267c237802d9a659dd21adcb7ec3ae Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Fri, 8 Aug 2008 14:34:13 -0700 Subject: Add documentation for the remctl PECL extension for PHP --- php/README | 220 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 php/README (limited to 'php') diff --git a/php/README b/php/README new file mode 100644 index 0000000..26b0fa1 --- /dev/null +++ b/php/README @@ -0,0 +1,220 @@ + remctl PECL Extension for PHP + +OVERVIEW + + The remctl PECL extension for PHP provides PHP bindings to the libremctl + client library. The provided interface is roughly the same as the C and + Perl interfaces, with some minor variations to be more consistent with + the normal PHP function interface. + + This PECL extension provides two interfaces, one which performs a single + call to a remctl server and returns the result, and another which + provides more control over the connection, returns individual output + tokens, and allows multiple commands to be sent via the same connection. + + This binding was originally written by Andrew Mortensen, with futher + modifications by Russ Allbery. + +REQUIREMENTS + + The module has only been tested with PHP 5.2 and may or may not work + with earlier versions. As with all libremctl bindings, it does not + itself obtain Kerberos tickets and requires that a Kerberos ticket cache + already be set up before making remctl calls. + + The PECL module build infrastructure provided is the one created by PHP + 5.2's phpize. Shipping the build infrastructure with the package is an + experiment that may not work. If you have build problems, try running + the phpize that comes with your version of PHP before running the main + remctl configure script. If that fixes the problem, please let me know. + A future version of remctl may run phpize during configure instead if + that causes fewer problems. + +SIMPLIFIED INTERFACE + + remctl(HOSTNAME, PORT, PRINCIPAL, COMMAND) + Runs COMMAND on the remote system and returns an object containing + the results. COMMAND should be an array of the type, the service, + and any parameters. HOSTNAME is the remote host to connect to. + PORT is the port; pass 0 to use the default library behavior (first + try 4373 and then fall back to 4444). PRINCIPAL is the principal of + the server to use for authentication; pass in the empty string to + use the default of host/HOSTNAME with the realm determined by + domain-realm mapping. + + The return value of remctl() is an object which will have the following + properties: + + error + The error message from the remote host or the local client library + if the remctl command fails. Set to the empty string if there was + no error. Checking whether error is the empty string is the + suppported way of determining whether the call succeeded. + + stdout + The command's standard output or null if there was none. + + stdout_len + The length of the command's standard output or 0 if there was none. + + stderr + The command's standard error or null if there was none. + + stderr_len + The length of the command's standard error or 0 if there was none. + + status + The exit status of the command. + + Here is an example using the simplified interface: + + dl('remctl.so'); + if (!extension_loaded('remctl')) { + echo "Failed to load remctl extension\n"; + exit(2); + } + $command = array('test', 'echo', 'hello world'); + $result = remctl('server.example.com', 0, '', $command); + if ($result->error) { + echo "remctl failed: $result->error\n"; + exit(2); + } + if ($result->stdout_len) { + echo "stdout: $result->stdout"; + } + if ($result->stderr_len) { + echo "stderr: $result->stderr"; + } + echo "status: $result->status"; + + Each call to remctl() will open a new connection to the remote host and + close it after retrieving the results of the command. + +FULL INTERFACE + + The full remctl interface requires the user to do more bookkeeping, but + provides more flexibility and visibility into what is happening at a + protocol level. It allows issuing multiple commands on the same + persistant connection (provided that the remote server supports protocol + version two; if it doesn't, the library will transparently fall back to + opening a connection for each command). + + To use the full interface, first create a connection object with + remctl_new(), connect to a server with remctl_connect(), and then issue + a command with remctl_command() and read output tokens with + remctl_output(). Once a status token has been received, the command is + complete and another command can be issued. + + The provided functions are: + + remctl_new() + Create a new connection object. This doesn't attempt to connect to + a host and will only fail if the extension cannot allocate memory. + + remctl_error(CONNECTION) + Returns, as a string, the error message from the last failed + operation on the connection object CONNECTION. + + remctl_open(CONNECTION, HOSTNAME[, PORT[, PRINCIPAL]]) + Connect to HOSTNAME on port PORT using PRINCIPAL as the remote + server's principal for authentication. If PORT is omitted or 0, use + the default (first try 4373, the registered remctl port, and fall + back to the legacy 4444 port if that fails). If PRINCIPAL is + omitted or the empty string, use the default of host/HOSTNAME, with + the realm determined by domain-realm mapping. Returns true on + success, false on failure. + + remctl_command(CONNECTION, COMMAND) + Send COMMAND (which should be an array) to the remote host. The + command may, under the remctl protocol, contain any character, but + be aware that most remctl servers will reject commands or arguments + containing ASCII 0 (NUL). This currently therefore cannot be used + for upload of arbitrary unencoded binary data. Returns true on + success (meaning success in sending the command and implying nothing + about the result of the command), and false on failure. + + remctl_output(CONNECTION) + Returns the next output token from the remote host. This will be an + object with one or more of the following properties: + + type + The type of the output token, which will be one of "output", + "error", "status", or "done". A command will result in either + one "error" token or zero or more "output" tokens followed by a + "status" token. The output is complete as soon as any token + other than an "output" token has been received, but the library + will keep returning "done" tokens to the caller for as long as + remctl_output() is called without another remctl_command(). + + data + Returns the contents of the token for either an "error" or + "output" token. The returned data may contain any character, + including ASCII 0 (NUL). + + stream + For an "output" token, returns the stream with which the data is + associated. Currently, this will either be 1 for standard + output or 2 for standard error. This value is undefined for all + other token types. + + status + For a "status" token, returns the exit status of the remote + command. This value is undefined for all other token types. + + error + For an "error" token, returns the remctl error code for the + protocol error. The text message will be returned in data. + + remctl_close(CONNECTION) + Explicitly close the connection and destroy the connection object. + This will also be done automatically when the object is destroyed, + so calling remctl_close explicitly is often not necessary. + + Here is an example using the full interface: + + dl('remctl.so'); + if (!extension_loaded('remctl')) { + echo "Failed to load remctl extension\n"; + exit(2); + } + $r = remctl_new(); + if ($r == null) { + echo "remctl_new failed\n"; + exit(2); + } + if (!remctl_open($r, 'server.example.com')) { + echo "remctl_open failed: " . remctl_error($r) . "\n"; + exit(2); + } + $command = array('test', 'echo', 'hello world'); + if (!remctl_command($r, $command)) { + echo "remctl_command failed: " . remctl_error($r) . "\n"; + } + $output = remctl_output($r); + while ($output != null && $output->type != "done") { + switch($output->type) { + case "output": + if ($output->stream == 1) { + echo "stdout: $output->data"; + } elseif ($output->stream == 2) { + echo "stderr: $output->data"; + } + break; + case "error": + echo "error: $output->error ($output->data)\n"; + break; + case "status": + echo "status: $output->status\n"; + break; + default: + echo "unknown output token type $output->type\n"; + } + $output = remctl_output($r); + } + if ($output == null) { + echo "remctl_output failed: " . remctl_error($r) . "\n"; + exit(2); + } + remctl_close($r) + + As mentioned above, the final remctl_close() is normally not needed. -- cgit v1.2.3