source: web/old/remctl-2.14/docs/api/remctl.3 @ f6f3e91

web
Last change on this file since f6f3e91 was f6f3e91, checked in by Jessica B. Hamrick <jhamrick@…>, 15 years ago

Preserve directory hierarchy (not sure what happened to it)

  • Property mode set to 100644
File size: 9.7 KB
Line 
1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings.  \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27.    ds -- \(*W-
28.    ds PI pi
29.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31.    ds L" ""
32.    ds R" ""
33.    ds C` ""
34.    ds C' ""
35'br\}
36.el\{\
37.    ds -- \|\(em\|
38.    ds PI \(*p
39.    ds L" ``
40.    ds R" ''
41'br\}
42.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el       .ds Aq '
46.\"
47.\" If the F register is turned on, we'll generate index entries on stderr for
48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49.\" entries marked with X<> in POD.  Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
51.ie \nF \{\
52.    de IX
53.    tm Index:\\$1\t\\n%\t"\\$2"
54..
55.    nr % 0
56.    rr F
57.\}
58.el \{\
59.    de IX
60..
61.\}
62.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65.    \" fudge factors for nroff and troff
66.if n \{\
67.    ds #H 0
68.    ds #V .8m
69.    ds #F .3m
70.    ds #[ \f1
71.    ds #] \fP
72.\}
73.if t \{\
74.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75.    ds #V .6m
76.    ds #F 0
77.    ds #[ \&
78.    ds #] \&
79.\}
80.    \" simple accents for nroff and troff
81.if n \{\
82.    ds ' \&
83.    ds ` \&
84.    ds ^ \&
85.    ds , \&
86.    ds ~ ~
87.    ds /
88.\}
89.if t \{\
90.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96.\}
97.    \" troff and (daisy-wheel) nroff accents
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
107.    \" corrections for vroff
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110.    \" for low resolution devices (crt and lpr)
111.if \n(.H>23 .if \n(.V>19 \
112\{\
113.    ds : e
114.    ds 8 ss
115.    ds o a
116.    ds d- d\h'-1'\(ga
117.    ds D- D\h'-1'\(hy
118.    ds th \o'bp'
119.    ds Th \o'LP'
120.    ds ae ae
121.    ds Ae AE
122.\}
123.rm #[ #] #H #V #F C
124.\" ========================================================================
125.\"
126.IX Title "REMCTL 3"
127.TH REMCTL 3 "2009-05-22" "2.14" "remctl Library Reference"
128.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
132.SH "NAME"
133remctl, remctl_result_free \- Simple remctl call to a remote server
134.SH "SYNOPSIS"
135.IX Header "SYNOPSIS"
136#include <remctl.h>
137.PP
138struct remctl_result *
139 \fBremctl\fR(const char *\fIhost\fR, unsigned short \fIport\fR,
140        const char *\fIprincipal\fR, const char **\fIcommand\fR);
141.PP
142void \fBremctl_result_free\fR(struct remctl_result *\fIresult\fR);
143.SH "DESCRIPTION"
144.IX Header "DESCRIPTION"
145\&\fIremctl()\fR provides a simplified client \s-1API\s0 for the remctl protocol.  Given
146the host, port, service principal for authentication, and command to run,
147it opens a connection to the remote system, sends the command via the
148remctl protocol, reads the results, closes the connection, and returns the
149result as a remctl_result struct.
150.PP
151\&\fIhost\fR is a hostname or \s-1IP\s0 address and must be non-NULL.  \fIport\fR is the
152port to connect to; if 0, the library first attempts to connect to the
153registered port of 4373 and then tries the legacy port of 4444 if that
154fails.  Future versions of the library will drop this fallback to 4444.
155\&\fIprincipal\fR is the service principal to use for authentication; if \s-1NULL\s0,
156\&\f(CW\*(C`host/\f(CIhost\f(CW\*(C'\fR is used, with the realm determined by domain-realm
157mapping.  \fIcommand\fR is the command to run as a NULL-terminated array of
158NUL-terminated strings.
159.PP
160If no principal is specified and the default is used, the underlying
161GSS-API library may canonicalize \fIhost\fR via \s-1DNS\s0 before determining the
162service principal, depending on your library configuration.  Specifying a
163principal disables this behavior.
164.PP
165The remctl protocol uses Kerberos v5 via GSS-API for authentication.  The
166underlying GSS-API library will use the default ticket cache for
167authentication, so to successfully use \fIremctl()\fR, the caller should already
168have Kerberos tickets for an appropriate realm stored in its default
169ticket cache.  The environment variable \s-1KRB5CCNAME\s0 can be used to control
170which ticket cache is used.
171.PP
172\&\fIremctl()\fR returns a newly allocated remctl_result struct, which has the
173following members:
174.PP
175.Vb 8
176\&    struct remctl_result {
177\&        char *error;                /* remctl error if non\-NULL. */
178\&        char *stdout_buf;           /* Standard output. */
179\&        size_t stdout_len;          /* Length of standard output. */
180\&        char *stderr_buf;           /* Standard error. */
181\&        size_t stderr_len;          /* Length of standard error. */
182\&        int status;                 /* Exit status of remote command. */
183\&    };
184.Ve
185.PP
186If error is non-NULL, a protocol error occurred and the command was not
187successfully completed.  Otherwise, standard output from the command will
188be stored in stdout_buf with the length in stdout_len, standard error from
189the command will be stored in stderr_buf with the length in stderr_len,
190and status will hold the exit status of the command.  Following the
191standard Unix convention, a 0 status should normally be considered success
192and any non-zero status should normally be considered failure, although a
193given command may have its own exit status conventions.
194.PP
195\&\fIremctl_result_free()\fR frees the remctl_result struct when the calling
196program is through with it.
197.PP
198If you want more control over the steps of the protocol, if you want to
199issue multiple commands on the same connection, or if you need to send
200data as part of the command that contains NULs, use the full \s-1API\s0 described
201in \fIremctl_new\fR\|(3), \fIremctl_open\fR\|(3), \fIremctl_commandv\fR\|(3), and
202\&\fIremctl_output\fR\|(3).
203.SH "RETURN VALUE"
204.IX Header "RETURN VALUE"
205\&\fIremctl()\fR returns \s-1NULL\s0 on failure to allocate a new remctl_result struct or
206on failure to allocate space to store an error message.  Otherwise, it
207returns a newly allocated remctl_result struct with either an error
208message in the error field or the results of the command filled out as
209described above.  If \fIremctl()\fR returns \s-1NULL\s0, errno will be set to an
210appropriate error code (generally \s-1ENOMEM\s0).
211.SH "CAVEATS"
212.IX Header "CAVEATS"
213If the \fIprincipal\fR argument to \fIremctl()\fR is \s-1NULL\s0, most GSS-API libraries
214will canonicalize the \fIhost\fR using \s-1DNS\s0 before deriving the principal name
215from it.  This means that when connecting to a remctl server via a \s-1CNAME\s0,
216\&\fIremctl()\fR will normally authenticate using a principal based on the
217canonical name of the host instead of the specified \fIhost\fR parameter.
218This behavior may cause problems if two consecutive \s-1DNS\s0 lookups of \fIhost\fR
219may return two different results, such as with some DNS-based
220load-balancing systems.
221.PP
222The canonicalization behavior is controlled by the GSS-API library; with
223the \s-1MIT\s0 Kerberos GSS-API library, canonicalization can be disabled by
224setting \f(CW\*(C`rdns\*(C'\fR to false in the [libdefaults] section of \fIkrb5.conf\fR.  It
225can also be disabled by passing an explicit Kerberos principal name via
226the \fIprincipal\fR argument, which will then be used without changes.  If
227canonicalization is desired, the caller may wish to canonicalize \fIhost\fR
228before calling \fIremctl()\fR to avoid problems with multiple \s-1DNS\s0 calls
229returning different results.
230.PP
231The default behavior, when a port of 0 is given, of trying 4373 and
232falling back to 4444 will be removed in a future version of this library
233in favor of using the \f(CW\*(C`remctl\*(C'\fR service in \fI/etc/services\fR if set and
234then falling back on only 4373.  4444 was the poorly-chosen original
235remctl port and should be phased out.
236.SH "NOTES"
237.IX Header "NOTES"
238The remctl port number, 4373, was derived by tracing the diagonals of a
239\&\s-1QWERTY\s0 keyboard up from the letters \f(CW\*(C`remc\*(C'\fR to the number row.
240.SH "SEE ALSO"
241.IX Header "SEE ALSO"
242\&\fIremctl_new\fR\|(3), \fIremctl_open\fR\|(3), \fIremctl_command\fR\|(3), \fIremctl_commandv\fR\|(3),
243\&\fIremctl_output\fR\|(3), \fIremctl_close\fR\|(3)
244.PP
245The current version of the remctl library and complete details of the
246remctl protocol are available from its web page at
247<http://www.eyrie.org/~eagle/software/remctl/>.
248.SH "AUTHOR"
249.IX Header "AUTHOR"
250Russ Allbery <rra@stanford.edu>
Note: See TracBrowser for help on using the repository browser.