source: web/old/remctl-2.14/docs/api/remctl_open.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: 7.5 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_OPEN 3"
127.TH REMCTL_OPEN 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_open \- Connect to a remote remctl server
134.SH "SYNOPSIS"
135.IX Header "SYNOPSIS"
136#include <remctl.h>
137.PP
138int \fBremctl_open\fR(struct remctl *\fIr\fR, const char *\fIhost\fR,
139                   unsigned short \fIport\fR,
140                   const char *\fIprincipal\fR);
141.SH "DESCRIPTION"
142.IX Header "DESCRIPTION"
143\&\fIremctl_open()\fR opens a \s-1TCP\s0 connection to the given \fIhost\fR on the given
144\&\fIport\fR and then authenticates using the remctl protocol and the service
145principal \fIprincipal\fR.  \fIr\fR is a remctl struct created via \fIremctl_new()\fR.
146\&\fIhost\fR must not be \s-1NULL\s0.  If \fIport\fR is 0, the library first attempts to
147connect to the registered port of 4373 and then tries the legacy port of
1484444 if that fails.  Future versions of the library will drop this
149fallback to 4444.  If \fIprincipal\fR is \s-1NULL\s0, a service principal of
150\&\f(CW\*(C`host/\f(CIhost\f(CW\*(C'\fR is used, with the realm determined by domain-realm
151mapping.
152.PP
153If no principal is specified and the default is used, the underlying
154GSS-API library may canonicalize \fIhost\fR via \s-1DNS\s0 before determining the
155service principal, depending on your library configuration.  Specifying a
156principal disables this behavior.
157.PP
158The remctl protocol uses Kerberos v5 via GSS-API for authentication.  The
159underlying GSS-API library will use the default ticket cache for
160authentication, so to successfully use \fIremctl_open()\fR, the caller should
161already have Kerberos tickets for an appropriate realm stored in its
162default ticket cache.  The environment variable \s-1KRB5CCNAME\s0 can be used to
163control which ticket cache is used.
164.SH "RETURN VALUE"
165.IX Header "RETURN VALUE"
166\&\fIremctl_open()\fR returns true on success and false on failure.  On failure,
167the caller should call \fIremctl_error()\fR to retrieve the error message.
168.SH "CAVEATS"
169.IX Header "CAVEATS"
170If the \fIprincipal\fR argument to \fIremctl_open()\fR is \s-1NULL\s0, most GSS-API
171libraries will canonicalize the \fIhost\fR using \s-1DNS\s0 before deriving the
172principal name from it.  This means that when connecting to a remctl
173server via a \s-1CNAME\s0, \fIremctl_open()\fR will normally authenticate using a
174principal based on the canonical name of the host instead of the specified
175\&\fIhost\fR parameter.  This behavior may cause problems if two consecutive
176\&\s-1DNS\s0 lookups of \fIhost\fR may return two different results, such as with some
177DNS-based load-balancing systems.
178.PP
179The canonicalization behavior is controlled by the GSS-API library; with
180the \s-1MIT\s0 Kerberos GSS-API library, canonicalization can be disabled by
181setting \f(CW\*(C`rdns\*(C'\fR to false in the [libdefaults] section of \fIkrb5.conf\fR.  It
182can also be disabled by passing an explicit Kerberos principal name via
183the \fIprincipal\fR argument, which will then be used without changes.  If
184canonicalization is desired, the caller may wish to canonicalize \fIhost\fR
185before calling \fIremctl_open()\fR to avoid problems with multiple \s-1DNS\s0 calls
186returning different results.
187.PP
188The default behavior, when a port of 0 is given, of trying 4373 and
189falling back to 4444 will be removed in a future version of this library
190in favor of using the \f(CW\*(C`remctl\*(C'\fR service in \fI/etc/services\fR if set and
191then falling back on only 4373.  4444 was the poorly-chosen original
192remctl port and should be phased out.
193.SH "NOTES"
194.IX Header "NOTES"
195The remctl port number, 4373, was derived by tracing the diagonals of a
196\&\s-1QWERTY\s0 keyboard up from the letters \f(CW\*(C`remc\*(C'\fR to the number row.
197.SH "SEE ALSO"
198.IX Header "SEE ALSO"
199\&\fIremctl_new\fR\|(3), \fIremctl_error\fR\|(3)
200.PP
201The current version of the remctl library and complete details of the
202remctl protocol are available from its web page at
203<http://www.eyrie.org/~eagle/software/remctl/>.
204.SH "AUTHOR"
205.IX Header "AUTHOR"
206Russ Allbery <rra@stanford.edu>
Note: See TracBrowser for help on using the repository browser.