source: web/old/remctl-2.14/docs/extending @ 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: 8.3 KB
Line 
1                             Extending remctl
2
3Introduction
4
5    This is a guide for users and implementors of remctl who notice
6    features or support currently missing and want to see how to add it,
7    or who are curious which parts of remctl can be easily extended and
8    which parts are more difficult.  Most of the easy extensibility is on
9    the server, which is written to permit straightforward addition of new
10    features, particularly to the configuration and ACL files.
11
12    Extension areas are presented here in roughly the order of complexity
13    of additions.
14
15    If you're considering extending remctl, please feel free to contact me
16    at rra@stanford.edu and let me know what you're planning and what
17    problem you're trying to solve.  I'm generally happy to offer advice
18    and incorporate and maintain extensions in the base distribution, even
19    if they're optional features that require external libraries to build.
20
21ACL Methods
22
23    remctl currently supports four ACL methods, but there is support in
24    the ACL syntax for tagging an ACL with a new method and it's
25    relatively straightforward to add new ACL methods to the server.
26
27    An ACL method name may be any alphanumerics plus hyphen (-).  The
28    current methods are defined in server/config.c (but may be broken int
29    a separate file if many more ACL methods are added).  The methods
30    struct defined in that file associates method names with the function
31    implementing that method.
32
33    To add a new ACL method, first write a function that checks a given
34    user against an ACL of that method.  Your function must take four
35    arguments: the remote username as a string, the ACL data as a string
36    (this is the part after the colon in the ACL for the current command),
37    and the file and line number in the ACL for error reporting.  The
38    function must return CONFIG_SUCCESS if the user is authorized by that
39    ACL data, CONFIG_NOMATCH if they are not, and CONFIG_ERROR on some
40    sort of failure, such as failure of a remote service or a syntax error
41    in the ACL data.
42
43    For example, the standard acl_check_princ function which implements
44    the princ ACL method does a string comparison of the ACL data to the
45    remote user identity and returns CONFIG_SUCCESS if they match and
46    CONFIG_NOMATCH otherwise.
47
48    Once you've written that function, add it and its method name to the
49    methods struct definition in server/config.c.  That's all there is to
50    it (although if you're submitting it for inclusion into remctl,
51    documentation additions to docs/remctld.pod and either a new test
52    suite or an addition to tests/server/acl-t.c would be nice).
53
54Config Options
55
56    remctld configuration options are handled somewhat similarly to ACLs,
57    but implementing them is likely to require more work since most new
58    options will not be as self-contained in only one portion of remctld.
59    But apart from implementing the effects of the option, adding a new
60    option is straightforward.
61
62    An option name must begin with a letter and may contain any
63    alphanumerics plus hyphen (-).  All options must have a value, and
64    options are always written in the configuration file as
65    <option>=<value>, after the command and before any ACLs.  Boolean
66    options should interpret "yes", "on", "true", and "1" as turning them
67    on and "no", "off", "false", and "0" as turning them off.
68
69    To add a new option, first write a parser for it in server/config.c.
70    That function should have a name starting with option_ and will take a
71    pointer to the configuration line, the value of the option as a
72    string, and the name and line number of the configuration file for
73    error reporting.  It should return CONFIG_SUCCESS on successful
74    parsing and CONFIG_ERROR on any error to parse (such as a syntax
75    error).
76
77    What the function does is up to you, but normally configuration
78    options will add an additional member to the confline struct and the
79    parser should analyze the value of the option and add the appropriate
80    parsed information to the confline struct.  Then, elsewhere (usually
81    in server/command.c), once the command being run has been determined,
82    that data can be used to do whatever the option is supposed to do.
83    The members of the confline struct are defined in server/internal.h.
84
85    As with ACL methods, if you submit the new option for inclusion,
86    documentation for docs/remctld.pod and either a new test case or an
87    addition to an existing test case are appreciated.  (If you don't
88    write them, I'll have to in order to incorporate the code.)
89
90Client Library
91
92    The main way in which people have wanted to enhance the client library
93    is to add bindings for additional programming languages.  remctl now
94    supports Perl, PHP, and Python, as well as a separate implementation
95    in Java, but there are many other languages that could be added (Ruby,
96    for example).
97
98    I'm happy to include new language bindings in the main remctl
99    distribution, and will also try to do the work to build packages for
100    Debian and Ubuntu.  Please follow the following guidelines for adding
101    new language bindings:
102
103    * Bindings for the C library rather than a native reimplementation in
104      that language is preferred.  Java is something of a special
105      exception in that it's expected to run without external
106      dependencies, but additional protocol implementations make for more
107      maintenance work in the long run.  If there are problems with the C
108      interface that prevent you from using the C libraries, talk to me
109      and I'll try to help.
110
111    * While the interface should adjust for the language, please try to
112      keep both the terminology and basics of the interface relatively
113      consistent with the C library.  Specifically, there should probably
114      be a simple interface that runs a command and returns the result as
115      an object or hash, and a more complex interface that permits sending
116      multiple commands and reading the individual output, status, or
117      error tokens from the server.
118
119    * The C interface allows optional parameters to remctl and remctl_open
120      and defaults to trying particular port numbers and principals for
121      the server.  Please preserve these optional parameters and defaults
122      in the language bindings.
123
124    * Please use the "native" way the language provides to write bindings.
125      In particular, please don't use SWIG unless that's what the language
126      community actively recommends.
127
128    * Please include a test suite in the native module testing mechanism
129      used by that language.
130
131    * Language bindings should be optional and not built by default.  They
132      should be enabled with a --enable-<lauguage> flag to configure.  See
133      the existing configure logic for the languages already supported and
134      the Makefile.am code for doing optional builds for examples.
135
136    * The build must support building in a directory other than the source
137      directory with the source files set read-only.  This may mean that
138      you need to copy some files from the source directory to the build
139      directory if builddir != srcdir, since most language build systems
140      don't support VPATH builds.  See Makefile.am for how that's handled
141      for existing languages and copy that setup.
142
143    * Please include a README or some other documentation for users of
144      that language explaining the complete interface.  php/README and
145      python/README are good examples.
146
147Protocol
148
149    The remctl protocol is designed to be extensible by introducing a new
150    protocol version.  All commands come tagged with the protocol version
151    required to understand them, and the server will automatically reject,
152    with a version error, protocol commands with too high of a version.
153    The client can also ask the server what version it supports.
154
155    Currently, the protocol version is two.  An initial draft of the
156    changes for protocol version three is available in docs/protocol-v3,
157    but may change prior to implementation.
158
159    The remctl protocol is defined by docs/protocol.xml, which is
160    translated into docs/protocol.txt and docs/protocl.html by xml2rfc.
161    Any changes to the protocol should be documented here.
162
163    I would like to keep remctl interoperable, so please talk to me before
164    making changes that would modify the protocol.
Note: See TracBrowser for help on using the repository browser.