Skip to content

Commit

Permalink
Update the CLI help.
Browse files Browse the repository at this point in the history
  • Loading branch information
@jjg-123
jjg-123 committed Nov 3, 2024
1 parent 9c72668 commit cfb9a5f
Showing 1 changed file with 118 additions and 102 deletions.
220 changes: 118 additions & 102 deletions website/src/site/xhtml/server/manuals/cli.xhtml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Command line tools</title>
<!--#include virtual="../../head.html" -->

<!--
This needs to be rewritten so that it refers to the basic CLI on the sec-lib
website, then has blurbs for each extension. The blurbs are in the QDL
Expand Down Expand Up @@ -74,7 +72,6 @@
-->
</head>
<body class="composite">
<!--#include virtual="../../header.html" -->
<h1>Command line tools for OA4MP</h1>

These are a set of programs that are accessible from a CLI
Expand All @@ -84,98 +81,42 @@ records and approvals. There is also the option to copy a store completely from
store to another.

<h2>Getting the tools</h2>

<p>The latest version of the Oauth 2.0 command line tool is available at
<a href="https://github.com/ncsa/oa4mp/releases/latest/oa2-cli.jar">oa2-cli.jar</a>
You should also get the script that runs this too,
<a href="https://github.com/ncsa/oa4mp/releases/latest/oa2-cli">oa2-cli</a>
<p>
Generally you should <a href="https://github.com/ncsa/oa4mp/releases/latest/download/server-installer.jar">use the installer</a>
and follow the instructions for that. This will deploy and configure a fully functional
CLI for your server. If you <i>really</i> insist on downloading and running the jar manually,
please the <a href="#appendix">Appendix</a>.
</p>
<h2>Configuration</h2>
The tool uses a standard configuration file exactly like the server. Indeed, you can just

<h3>Configuration</h3>
<p>The tool uses a standard configuration file exactly like the server. Indeed, you can
(and generally should) just
point the tool at the server configuration file. You will need to supply the name of
the configuration in the file you want to use. Aliases can be quite handy here. Given the abilities of
the configuration in the file you want to use. Configuration file aliases (these are internal
to the can be quite handy here. Given the abilities of
the CLI to do quick copies of the store, it pays to have a backup (file) store configured and
occasionally simple copy the active store to that. There are many possible uses. It is assumed that
the tools are installed in a location called $OA4MP_HOME. Normally the default for this is
the tools are installed in a location called $OA4MP_SERVER. Normally the default for this is
<br/><br/>
OAuth 1.0a: OA4MP_HOME=/opt/oa4mp
<br/><br/>
OAuth 2.0: OA4MP_HOME=opt/oa2

<b>Note that we will be discussing the OA4MP tools rather than the OA2 tools in what follows.
Everything here works the same if you replace oa4mp-* by oa2-*</b
>
OA4MP_SERVER=/opt/oa4mp/server
</p>
<p>The assumption of the script is that files are in the following directory structure</p>
<ul>
<li><code>$OA4MP_HOME/etc/admin-cfg.xml</code> - the configuration file</li>
<li><code>$OA4MP_HOME/lib/oa4mp-cli.jar</code> - the jar containing the CLI</li>
<li><code>$OA4MP_HOME/bin/oa4mp-cli</code> - the script for running this. Be sure it is set to be executable.</li>
<li><code>$OA4MP_SERVER/etc/admin-cfg.xml</code> - the configuration file</li>
<li><code>$OA4MP_SERVER/lib/cli.jar</code> - the jar containing the CLI</li>
<li><code>$OA4MP_SERVER/bin/cli</code> - the script for running this. Be sure it is set to be executable.</li>
</ul>
The default name of the configuration is assumed to be "default" (no quotes). If you invoke the script with
no arguments it will use this and the above configuration file.

<h2>Running the CLI</h2>
Invocation from the command line is usually done with the supplied shell script, oa4mp-cli. The
invocation syntax is <br/>

<pre>oa4mp-cli [configName configFile]</pre>

You should run this as root and might need to set the script to be
executable if it is not. If you give neither arguments then defaults are used. Invoke with the argument "--help"
for more information. If you give one argument it is assumed to be the configuration name
in the default configuration file.
<h2>Command line options for the jar.</h2>
You should run this from the script, but if you want or need to specify
invoke the jar directly, the invocation options they are listed here.
<table style="text-align: left; width: 1157px; height: 165px;" border="1" cellspacing="2" cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Argument</td>
<td style="vertical-align: top;">Value required?</td>
<td style="vertical-align: top;">Required?</td>
<td style="vertical-align: top;">Description</td>
</tr>
<tr>
<td style="vertical-align: top;">-cfg</td>
<td style="vertical-align: top;">Y</td>
<td style="vertical-align: top;">Y</td>
<td style="vertical-align: top;">The full path to the configuration file.</td>
</tr>
<tr>
<td style="vertical-align: top;">-name</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">The name of the configuration within the file. If there is a single configuration
in the file, then no name is needed. If there are multiple configurations you must specify which one to use. </td>
</tr>
<tr>
<td style="vertical-align: top;">-log</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">The full path log file. If this is not specified then a file named "log.xml"
is dumped into the invocation directory.</td>
</tr>
<tr>
<td style="vertical-align: top;">-use</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">Specify the component to use. Rather than loading the whole CLI then <b>use</b>-ing
a components (such as clients) you may simply specify that here.</td>
</tr>
<tr>
<td style="vertical-align: top;">-v</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">No argument. Turns on verbose logging so that much more information is dumped
onto the console. This is useful for debugging or just if you want to see what it is up to.</td>
</tr>
</tbody>
</table>
<pre>
java -jar oa4mp-cli.jar -cfg /path/to/cfg.xml -name myConfig -log /path/to/mylog.xml -use approvals
</pre>
This would load the configuration named "myConfig" from the given file, write the log to a file called
"mylog.xml" and bring up the approvals component.
<p>The default name of the configuration is assumed to be "default" (no quotes). If you invoke the script with
no arguments it will use this and the above configuration file. Invocation syntax is</p>

<pre>java -jar $OA4MP_SERVER/lib/cli.jar [configName configFile env]</pre>
<ol>
<li>configName = name of the configuration in the file</li>
<li>configFile = full path to the configuration file</li>
<li>env = full path to a properties fiel that has environment variables set in it.
(This is specialized and can usually be omitted.)</li>
</ol>
<p>Note that you may shorten the list, but cannot, e.g., just supply the configuration file.</p>

<h2>Help!</h2>
<p>For every command you may add the switch <code>--help</code> and you will get
Expand Down Expand Up @@ -227,14 +168,16 @@ view the help for the <b>ls</b> command:</p>
</p>

<h2>Meta commands</h2>
<p>There are commands to do tasks and there are <i>meta-commands</i> that control how the
<p>The OA4MP CLI extends the <a href="https://ncsa.github.io/security-lib/cli/index.html">NCSA CLI framework</a>,
so meta commands are more fully discussed there.
There are commands to do tasks and there are <i>meta-commands</i> that control how the
CLI itself operates. These are prefixed with a backslash <b>/</b>. E.g. to quit a component,
issue</p>
<pre>/q</pre>
<p>A full listing of meta commands is done with the ?:</p>
<pre>/?</pre>
<p>Extremely use meta-commands are a command history, executing a command in another component
with out switching from the current one, saving you command history (useful if you want
<p>Commonly used meta-commands are a command history, executing a command in another component
without switching from the current one, saving you command history (useful if you want
to use a set of commands as a basis for some scripting). To list the commands available for
the admin component, you would issue</p>
<pre>
Expand Down Expand Up @@ -264,7 +207,7 @@ will just change to that component and exiting it will return to you the origina
The CLI consists of utilities for each component that can be used. Once invoked you will see
the startup banner and prompt:
<pre>
[mybox bin]# ./oa4mp-cli
[mybox bin]# ./cli
**********************************************************
* OA4MP CLI (Command Line Interpreter) *
* Version 6.0 *
Expand All @@ -274,11 +217,11 @@ the startup banner and prompt:
* type 'help' for a list of commands *
* 'exit' or 'quit' to end this session. *
**********************************************************
oa2>
oa4mp>
</pre>
If you type "--help" You will get
<pre>
oa2>--help
oa4mp>--help

Here are the commands available:
use
Expand All @@ -296,7 +239,7 @@ Basic supported commands are

To see the help for, say, the use command you would issue
<pre>
oa2>use --help
oa4mp>use --help
Choose the component you wish to use.
you specify the component as use + name. Supported components are
clients - edit client records
Expand Down Expand Up @@ -351,8 +294,8 @@ operations with the </p>
<p>command. Related is the <b>get_id</b> to display the current id and the <b>clear_id</b>
to clear it. If you have an default id set, you do not need to specify one.</p>
<pre>
oa2>set_id foo:bar/34456
oa2>ls -l
oa4mp>set_id foo:bar/34456
oa4mp>ls -l
name : My test thing
id : foo:bar/34456
</pre>
Expand Down Expand Up @@ -382,12 +325,12 @@ This will print the number of elements in the current storage component. <br/>
<i>Example.</i> For showing the number of clients in a store
you would have something like the following
<pre>
oa2>use clients
oa4mp>use clients
clients >size
Current store has 22 entries
clients >exit
exiting ...
oa2>
oa4mp>
</pre>

<h4><a name="ls">Listing Object or Details of an Object.</a></h4>
Expand Down Expand Up @@ -644,7 +587,7 @@ deserialization commands against it repeatedly as you debug it.</p>

<h2><a name="clients">Clients</a></h2>
Invoke as
<pre>oa2> use clients</pre>
<pre>oa4mp> use clients</pre>
Operations allowed in addition to the standard ones are
<ul>
<li>
Expand Down Expand Up @@ -673,14 +616,14 @@ clients>

<h2><a name="approvals">Approvals</a></h2>
Invoke as
<pre>oa2> use approvals</pre>
<pre>oa4mp> use approvals</pre>
There are no extra options beyond the standard ones, however, the <code>create</code> command
takes the unique id of the client record you are going to approve. Once created, you may enter the
approval information directly.

<h2><a name="copy">Copy</a></h2>
Invoke as
<pre>oa2>use copy</pre>
<pre>oa4mp>use copy</pre>
Supported operation is
<ul>
<li>cp source target [-verify] - copy source to target optionally verifying</li>
Expand All @@ -691,7 +634,80 @@ that the every object in the target is deleted, so no merge takes place. If the
then the two stores are compared once the copy has been completed. Note that this can be very time consuming
for a large store! However, if there is any question it is at times very useful.

<h1 id="appendix">Appendix</h1>
<h3>Getting and installing it manually</h3>
<p>You <i>can</i> just download the jar and configure it manually, though that is a lot more
work than the installer. One cogent argument is incorporating the CLI into your own custome scripts.
This section is how to run the CLI fromthe jara manually. If you use the installer,
skip this section.</p>
<p>The latest version of the OA4MP command line tool is available at
<a href="https://github.com/ncsa/oa4mp/releases/latest/download/cli.jar">cli.jar</a>
You should also get the script that runs this too,
<a href="https://github.com/ncsa/oa4mp/releases/latest/cli">cli</a>
</p>
<p>If you are pointing to the server configuration, you will probably need to run this as root
to get access top that file. If you invoke the CLI with no arguments, it will tell
you there is no configuration, but you can use all of the online help.
You need the configuration file and name of the configuration generally to get a working
CLI.</p>

<h4>Running the CLI jar</h4>
<p>invocation syntax is just like any other executable jar</p>

<pre>java -jar $OA4MP_SERVER/lib/cli.jar <i>options</i></pre>

<h4>Command line options for the jar.</h4>
You should run this from the script, but if you want or need to specify
invoke the jar directly, the invocation options they are listed here.
<table style="text-align: left; width: 1157px; height: 165px;" border="1" cellspacing="2" cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Argument</td>
<td style="vertical-align: top;">Value required?</td>
<td style="vertical-align: top;">Required?</td>
<td style="vertical-align: top;">Description</td>
</tr>
<tr>
<td style="vertical-align: top;">-cfg</td>
<td style="vertical-align: top;">Y</td>
<td style="vertical-align: top;">Y</td>
<td style="vertical-align: top;">The full path to the configuration file.</td>
</tr>
<tr>
<td style="vertical-align: top;">-name</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">The name of the configuration within the file. If there is a single configuration
in the file, then no name is needed. If there are multiple configurations you must specify which one to use. </td>
</tr>
<tr>
<td style="vertical-align: top;">-log</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">The full path log file. If this is not specified then a file named "log.xml"
is dumped into the invocation directory.</td>
</tr>
<tr>
<td style="vertical-align: top;">-use</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">Specify the component to use. Rather than loading the whole CLI then <b>use</b>-ing
a components (such as clients) you may simply specify that here.</td>
</tr>
<tr>
<td style="vertical-align: top;">-v</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">F</td>
<td style="vertical-align: top;">No argument. Turns on verbose logging so that much more information is dumped
onto the console. This is useful for debugging or just if you want to see what it is up to.</td>
</tr>
</tbody>
</table>
<pre>
java -jar cli.jar -cfg /path/to/cfg.xml -name myConfig -log /path/to/mylog.xml -use approvals
</pre>
This would load the configuration named "myConfig" from the given file, write the log to a file called
"mylog.xml" and bring up the approvals component.

<!--#include virtual="../../footer.html" -->
</body>
</html>

0 comments on commit cfb9a5f

Please sign in to comment.