source: web/old/remctl-2.14/java/README @ 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: 5.4 KB
Line 
1                        remctl Java Implementation
2
3OVERVIEW
4
5  This directory contains a remctl implementation written in Java.  Both a
6  client and a server are included, and the implementation supports
7  version two of the remctl protocol.  Both client and server are written
8  natively in Java and are entirely independent of the C implementation.
9
10  This implementation is not as mature or as well-tested as the C
11  implementation.  Any feedback and bug reports are gratefully accepted.
12
13REQUIREMENTS
14
15  This implementation works with the Sun Java JDK 1.4.2, 5, and 6.  It
16  will not build with gcj; it could be ported, but wouldn't be useful
17  until gcj has com.sun.security.auth.module.Krb5LoginModule or an
18  equivalent.
19
20  You can use either the provided simple Makefile or ant to build the JAR
21  file.  This source tree will also build in Eclipse and includes an
22  Eclipse .project and .classpath file.
23
24  To use 256-bit AES keys, you will need to get the "Java Cryptography
25  Extension (ECE) Unlimited Strength Jurisdiction Policy Files 6"
26  (filename jce_policy-6.zip), which is available (at least to US
27  residents) from <http://java.sun.com/javase/downloads/index.jsp>.
28
29BUILDING
30
31  If you have ant available, it's the easiest way to build the JAR file.
32  Running ant dist will build the JAR file and put it in dist/lib.  You
33  may have to set ANT_HOME and JAVA_HOME to point ant at the appropriate
34  directories.
35
36  If you do not have ant, you can use the provided Makefile, which will
37  create the JAR file in the current directory.  If your JDK isn't at
38  /usr/lib/jvm/java-6-sun, either edit the Makefile to change JAVA_HOME
39  and then run make, set the JAVA_HOME variable on the command line with:
40
41      make JAVA_HOME=/path/to/jdk
42
43  or set JAVA_HOME in the environment.
44
45  However you do the build, create a k5.conf file by copying your
46  /etc/krb5.conf file and then adding these lines to the [libdefaults]
47  section:
48
49      default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc des-cbc-md5
50      default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc des-cbc-md5
51      permitted_enctypes = des3-hmac-sha1 des-cbc-crc des-cbc-md5
52
53  MIT Kerberos and Heimdal do not need this configuration and it is wrong
54  for them, but the built-in list for Sun Java is limited and it will
55  break if it encounters encryption types that it doesn't understand.  The
56  sample k5.conf in this directory can be used, but change the default
57  realm.
58
59  You can remove the DES enctypes if your realm doesn't support DES.  If
60  you are using Java 6, you can add aes128-cts to the beginning of each
61  list.  If you have the jce_policy-6.zip file installed, you can also add
62  aes256-cts to the beginning of each line.
63
64RUNNING
65
66  You can now run the client from the JAR file:
67
68      java -Djava.security.krb5.conf=k5.conf \
69          -Djava.security.auth.login.config=j3.conf -jar remctl-*.jar \
70          org.eyrie.eagle.remctl.RemctlClient \
71          <host> <command> <subcommand> [<parameter> ...]
72
73  This connects to the remctld on <host> and sends the command <type>
74  <service> <parameter>.  If you're using ant, the JAR file will be in
75  dist/lib instead.  You can also run the client from the class files:
76
77      java -Djava.security.krb5.conf=k5.conf \
78          -Djava.security.auth.login.config=j3.conf \
79          -cp build:. org.eyrie.eagle.remctl.RemctlClient \
80          <host> <command> <subcommand> [<parameter> ...]
81
82  Also look at t5.java for an example of how to use the class in a Java
83  program.
84
85  To run the server, create a keytab that the server will use for
86  authentication and revise bcsKeytab.conf to match (you will need to
87  change the principal at least).  Then, start the server with:
88
89      java -Djavax.security.auth.useSubjectCredsOnly=false \
90          -Djava.security.auth.login.config=bcsKeytab.conf -cp build:. \
91          t7 4373 <principal>
92
93  This will start the server defined in t7.java, which just returns
94  information about what command it received.  4373 is the port to listen
95  to (4373 is the default value for remctl).  Replace <principal> for the
96  principal you created a keytab for.
97
98  To run this from Eclipse, select from the Run, Run..., "java
99  application", make an instance for the selected Main Class.  Under
100  Arguments, set VM arguments to be those above for "java", and set the
101  program arguments to be everything past the jar file or main class.
102
103CREATING A DISTRIBUTION
104
105  The java directory of the remctl distribution is not structured like a
106  conventional Java distribution.  However, you can generate an
107  independent source distribution that looks much more like a standard
108  Java distribution using ant.  Optionally first run ant dist to build the
109  JAR file and then run ant tar to generate the distribution (which will
110  then be found in dist).  This generated distribution will be structured
111  like an Apache Jakarta project:
112
113      dist/lib          The built JAR file with the version in its name
114      doc               This documentation and the sample configuration
115      src               The JAR file source
116
117  The running instructions above will be slightly different if you use
118  this distribution, since the configuration files will be in doc instead
119  of at the top level and the test Java files will be in bin.
120
121HISTORY
122
123  This Java remctl implementation was written by Marcus Watts, based
124  somewhat on the original remctl Java implementation by Anton Ushakov.
125  The build system and this documentation is based on the build system and
126  documentation provided by Marcus.
Note: See TracBrowser for help on using the repository browser.