-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This uses the argparse_manpage Python package, which does a reasonably good job at turning the argparse parser into a manpage.
- Loading branch information
Showing
5 changed files
with
257 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,6 @@ | ||
__pycache__ | ||
.coverage | ||
*,cover | ||
build | ||
dist | ||
zeek_client.egg-info |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,80 @@ | ||
#!/usr/bin/env python3 | ||
# | ||
# A helper script to derive a zeek-client manpage from its argparse state. | ||
# | ||
import os.path | ||
import sys | ||
|
||
try: | ||
from argparse_manpage.manpage import Manpage | ||
except ImportError: | ||
print("The manpage builder needs the argparse_manpage package.") | ||
sys.exit(1) | ||
|
||
LOCALDIR = os.path.dirname(os.path.realpath(__file__)) | ||
ROOTDIR = os.path.normpath(os.path.join(LOCALDIR, "..")) | ||
|
||
# Prepend the project's toplevel directory to the search path so we import the | ||
# zeekclient package locally. | ||
sys.path.insert(0, ROOTDIR) | ||
|
||
import zeekclient.cli # pylint: disable=wrong-import-position,import-error | ||
|
||
|
||
def main(): | ||
parser = zeekclient.cli.create_parser() | ||
|
||
# The parser currently has this script as program name, so replace: | ||
parser.prog = "zeek-client" | ||
|
||
# Expand the description: | ||
parser.description = """A command-line client for Zeek's Management Framework. | ||
Use this client to push cluster configurations to a cluster controller, retrieve | ||
running state from the system, restart nodes, and more. | ||
For details about Zeek's Management Framework, please consult the documentation | ||
at https://docs.zeek.org/en/master/frameworks/management.html. | ||
""" | ||
# Remove the epilog -- it's more suitable for an ENVIRONMENT section. | ||
environment = parser.epilog | ||
parser.epilog = None | ||
|
||
# The 'single-commands-section' formatter spells out the details of every | ||
# subcommand as it lists each of those commands. | ||
manpage = Manpage(parser, format="single-commands-section") | ||
|
||
# The Manpage class cannot handle ":" in the usage string ("HOST:PORT"), | ||
# so replace the synopsis. Must yield a list of strings. | ||
manpage.synopsis = parser.format_usage().split(":", 1)[-1].split() | ||
|
||
manpage.add_section( | ||
"EXIT STATUS", | ||
">", | ||
"""The client exits with 0 on | ||
success and 1 if a problem arises, such as lack of a response from the | ||
controller, unexpected response data, or the controller explicitly reporting an | ||
error in its handling of a command.""", | ||
) | ||
|
||
# Create an environment section from the epilog in the parser. | ||
# We replace the first line to be more manpage-suitable. | ||
env = environment.splitlines() | ||
env = ["zeek-client supports the following environment variables:"] + env[1:] | ||
manpage.add_section("ENVIRONMENT", ">", "\n".join(env)) | ||
|
||
manpage.add_section( | ||
"SUGGESTIONS AND BUG REPORTS", | ||
">", | ||
"""The Management Framework and this client are experimental | ||
software. The Zeek team welcomes your feedback. Please file issues on Github at | ||
https://github.com/zeek/zeek-client/issues, or contact us on Discourse or Slack: | ||
https://zeek.org/community""", | ||
) | ||
|
||
with open("zeek-client.1", "w", encoding="ascii") as hdl: | ||
hdl.write(str(manpage)) | ||
|
||
|
||
if __name__ == "__main__": | ||
main() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,165 @@ | ||
.TH ZEEK\-CLIENT "1" "2023\-09\-08" "zeek\-client" "Generated Python Manual" | ||
.SH NAME | ||
zeek\-client | ||
.SH SYNOPSIS | ||
.B zeek\-client | ||
[-h] [-c FILE] [--controller HOST:PORT] [--set SECTION.KEY=VAL] [--quiet | --verbose] [--version] {deploy,deploy-config,get-config,get-id-value,get-instances,get-nodes,monitor,restart,stage-config,show-settings,test-timeout} ... | ||
.SH DESCRIPTION | ||
A command\-line client for Zeek's Management Framework. | ||
|
||
Use this client to push cluster configurations to a cluster controller, retrieve | ||
running state from the system, restart nodes, and more. | ||
|
||
For details about Zeek's Management Framework, please consult the documentation at | ||
https://docs.zeek.org/en/master/frameworks/management.html. | ||
|
||
.SH OPTIONS | ||
.TP | ||
\fB\-c\fR \fI\,FILE\/\fR, \fB\-\-configfile\fR \fI\,FILE\/\fR | ||
Path to zeek\-client config file. (Default: @ZEEK_CLIENT_CONFIG_FILE@) | ||
|
||
.TP | ||
\fB\-\-controller\fR \fI\,HOST:PORT\/\fR | ||
Address and port of the controller, either of which may be omitted (default: 127.0.0.1:2149) | ||
|
||
.TP | ||
\fB\-\-set\fR \fI\,SECTION.KEY=VAL\/\fR | ||
Adjust a configuration setting. Can use repeatedly. See show\-settings. | ||
|
||
.TP | ||
\fB\-\-quiet\fR, \fB\-q\fR | ||
Suppress informational output to stderr. | ||
|
||
.TP | ||
\fB\-\-verbose\fR, \fB\-v\fR | ||
Increase informational output to stderr. Repeat for more output (e.g. \-vvv). | ||
|
||
.TP | ||
\fB\-\-version\fR | ||
Show version number and exit. | ||
|
||
.SH | ||
COMMANDS | ||
.SS \fBzeek\-client deploy\fR | ||
Deploy a staged cluster configuration. | ||
|
||
usage: build.py deploy [\-h] | ||
.SS \fBzeek\-client deploy\-config\fR | ||
Upload a cluster configuration and deploy it. | ||
|
||
usage: build.py deploy\-config [\-h] FILE | ||
|
||
arguments: | ||
.RS 7 | ||
.TP | ||
\fBFILE\fR | ||
Cluster configuration file, "\-" for stdin | ||
.RE | ||
|
||
.SS \fBzeek\-client get\-config\fR | ||
Retrieve staged or deployed cluster configuration. | ||
|
||
usage: build.py get\-config [\-h] [\-\-filename FILE] [\-\-as\-json] [\-\-deployed | \-\-staged] | ||
|
||
options: | ||
.RS 7 | ||
.TP | ||
\fB\-\-filename\fR \fI\,FILE\/\fR, \fB\-f\fR \fI\,FILE\/\fR | ||
Output file for the configuration, default stdout | ||
|
||
.TP | ||
\fB\-\-as\-json\fR | ||
Report in JSON instead of INI\-style config file | ||
|
||
.TP | ||
\fB\-\-deployed\fR | ||
Return deployed configuration | ||
|
||
.TP | ||
\fB\-\-staged\fR | ||
Return staged configuration (default) | ||
.RE | ||
|
||
.SS \fBzeek\-client get\-id\-value\fR | ||
Show the value of a given identifier in Zeek cluster nodes. | ||
|
||
usage: build.py get\-id\-value [\-h] IDENTIFIER [NODES ...] | ||
|
||
arguments: | ||
.RS 7 | ||
.TP | ||
\fBIDENTIFIER\fR | ||
Name of the Zeek script identifier to retrieve. | ||
|
||
.TP | ||
\fBNODES\fR | ||
Name(s) of Zeek cluster nodes to query. When omitted, queries all nodes. | ||
.RE | ||
|
||
.SS \fBzeek\-client get\-instances\fR | ||
Show instances connected to the controller. | ||
|
||
usage: build.py get\-instances [\-h] | ||
.SS \fBzeek\-client get\-nodes\fR | ||
Show active Zeek nodes at each instance. | ||
|
||
usage: build.py get\-nodes [\-h] | ||
.SS \fBzeek\-client monitor\fR | ||
For troubleshooting: do nothing, just report events. | ||
|
||
usage: build.py monitor [\-h] | ||
.SS \fBzeek\-client restart\fR | ||
Restart cluster nodes. | ||
|
||
usage: build.py restart [\-h] [NODES ...] | ||
|
||
arguments: | ||
.RS 7 | ||
.TP | ||
\fBNODES\fR | ||
Name(s) of Zeek cluster nodes to restart. When omitted, restarts all nodes. | ||
.RE | ||
|
||
.SS \fBzeek\-client stage\-config\fR | ||
Upload a cluster configuration for later deployment. | ||
|
||
usage: build.py stage\-config [\-h] FILE | ||
|
||
arguments: | ||
.RS 7 | ||
.TP | ||
\fBFILE\fR | ||
Cluster configuration file, "\-" for stdin | ||
.RE | ||
|
||
.SS \fBzeek\-client show\-settings\fR | ||
Show zeek-client's own configuration. | ||
|
||
usage: build.py show\-settings [\-h] | ||
.SS \fBzeek\-client test\-timeout\fR | ||
Send timeout test event. | ||
|
||
usage: build.py test\-timeout [\-h] [\-\-with\-state] | ||
|
||
options: | ||
.RS 7 | ||
.TP | ||
\fB\-\-with\-state\fR | ||
Make request stateful in the controller. | ||
.RE | ||
|
||
.SH EXIT STATUS | ||
The client exits with 0 on | ||
success and 1 if a problem arises, such as lack of a response from the | ||
controller, unexpected response data, or the controller explicitly reporting an | ||
error in its handling of a command. | ||
.SH ENVIRONMENT | ||
zeek-client supports the following environment variables: | ||
|
||
ZEEK_CLIENT_CONFIG_FILE: Same as `--configfile` argument, but lower precedence. | ||
ZEEK_CLIENT_CONFIG_SETTINGS: Same as a space-separated series of `--set` arguments, but lower precedence. | ||
.SH SUGGESTIONS AND BUG REPORTS | ||
The Management Framework and this client are experimental | ||
software. The Zeek team welcomes your feedback. Please file issues on Github at | ||
https://github.com/zeek/zeek-client/issues, or contact us on Discourse or Slack: | ||
https://zeek.org/community |