Commit 8519ea87 authored by Mark Michelson's avatar Mark Michelson Committed by Ben Pfaff

Refer to database manpages in *ctl manpages

The ovn-nbctl, ovn-sbctl, and ovs-vsctl manpages are inconsistent in
their "Database Commands" section when it comes to referring to what
database tables exist. This commit amends this by making each *ctl
manpage reference the corresponding database manpage instead.

To aid in having a more handy list, the --help text of ovn-nbctl,
ovn-sbctl, and ovs-vsctl have been modified to list the available
tables. This is also referenced in the manpages for those applications.
Signed-off-by: default avatarMark Michelson <mmichels@redhat.com>
Signed-off-by: default avatarBen Pfaff <blp@ovn.org>
parent 2696bcb1
......@@ -35,6 +35,7 @@
#include "ovsdb-idl-provider.h"
#include "openvswitch/shash.h"
#include "sset.h"
#include "svec.h"
#include "string.h"
#include "table.h"
#include "util.h"
......@@ -61,6 +62,9 @@ static const struct cmd_show_table *cmd_show_tables;
static void (*ctl_exit_func)(int status) = NULL;
OVS_NO_RETURN static void ctl_exit(int status);
/* IDL class. */
static const struct ovsdb_idl_class *idl_class;
/* Two arrays with 'n_classes' elements, which represent the tables in this
* database and how the user can refer to their rows. */
static const struct ctl_table_class *ctl_classes;
......@@ -2132,15 +2136,15 @@ ctl_register_commands(const struct ctl_command_syntax *commands)
/* Registers the 'db_ctl_commands' to 'all_commands'. */
void
ctl_init__(const struct ovsdb_idl_table_class *idl_classes_,
ctl_init__(const struct ovsdb_idl_class *idl_class_,
const struct ctl_table_class *ctl_classes_,
size_t n_classes_,
const struct cmd_show_table cmd_show_tables_[],
void (*ctl_exit_func_)(int status))
{
idl_classes = idl_classes_;
idl_class = idl_class_;
idl_classes = idl_class_->tables;
ctl_classes = ctl_classes_;
n_classes = n_classes_;
n_classes = idl_class->n_tables;
ctl_exit_func = ctl_exit_func_;
ctl_register_commands(db_ctl_commands);
......@@ -2170,6 +2174,63 @@ ctl_get_db_cmd_usage(void)
Potentially unsafe database commands require --force option.\n";
}
const char *
ctl_list_db_tables_usage(void)
{
static struct ds s = DS_EMPTY_INITIALIZER;
if (s.length) {
return ds_cstr(&s);
}
ds_put_cstr(&s, "Database commands may reference a row in each table in the following ways:\n");
for (int i = 0; i < n_classes; i++) {
struct svec options = SVEC_EMPTY_INITIALIZER;
svec_add(&options, "by UUID");
if (idl_classes[i].is_singleton) {
svec_add(&options, "as \".\"");
}
for (int j = 0; j < ARRAY_SIZE(ctl_classes[i].row_ids); j++) {
const struct ctl_row_id *id = &ctl_classes[i].row_ids[j];
if (!id->name_column) {
continue;
}
struct ds o = DS_EMPTY_INITIALIZER;
if (id->uuid_column) {
ds_put_format(&o, "via \"%s\"", id->uuid_column->name);
const struct ovsdb_idl_table_class *referrer
= ovsdb_idl_table_class_from_column(idl_class,
id->uuid_column);
if (referrer != &idl_classes[i]) {
ds_put_format(&o, " of %s", referrer->name);
}
if (id->key) {
ds_put_format(&o, " with matching \"%s:%s\"",
id->name_column->name, id->key);
} else {
ds_put_format(&o, " with matching \"%s\"", id->name_column->name);
}
} else if (id->key) {
ds_put_format(&o, "by \"%s:%s\"", id->name_column->name, id->key);
} else {
ds_put_format(&o, "by \"%s\"", id->name_column->name);
}
svec_add_nocopy(&options, ds_steal_cstr(&o));
}
ds_put_format(&s, " %s:", idl_classes[i].name);
for (int j = 0; j < options.n; j++) {
ds_put_format(&s, "\n %s", options.names[j]);
}
ds_put_char(&s, '\n');
svec_destroy(&options);
}
return ds_cstr(&s);
}
/* Initializes 'ctx' from 'command'. */
void
ctl_context_init_command(struct ctl_context *ctx,
......
......@@ -51,13 +51,11 @@ struct cmd_show_table;
/* ctl_init() figures out the number of tables on its own and flags an error if
* 'ctl_classes' was defined with the wrong number of elements. */
#define ctl_init(idl_classes, ctl_classes, cmd_show_table, ctl_exit_func) \
(BUILD_ASSERT(ARRAY_SIZE(idl_classes) == ARRAY_SIZE(ctl_classes)), \
ctl_init__(idl_classes, ctl_classes, ARRAY_SIZE(idl_classes), \
cmd_show_table, ctl_exit_func))
void ctl_init__(const struct ovsdb_idl_table_class *idl_classes,
const struct ctl_table_class *ctl_classes,
size_t n_classes,
#define ctl_init(idl_class, table_classes, ctl_classes, cmd_show_table, \
ctl_exit_func) \
(BUILD_ASSERT(ARRAY_SIZE(table_classes) == ARRAY_SIZE(ctl_classes)), \
ctl_init__(idl_class, ctl_classes, cmd_show_table, ctl_exit_func))
void ctl_init__(const struct ovsdb_idl_class *, const struct ctl_table_class *,
const struct cmd_show_table *cmd_show_tables,
void (*ctl_exit_func)(int status));
char *ctl_default_db(void);
......@@ -159,6 +157,8 @@ struct ctl_command {
bool ctl_might_write_to_db(char **argv);
const char *ctl_get_db_cmd_usage(void);
const char *ctl_list_db_tables_usage(void);
void ctl_print_commands(void);
void ctl_print_options(const struct option *);
void ctl_add_cmd_options(struct option **, size_t *n_options_p,
......
......@@ -68,6 +68,11 @@ char *alloc_nat_zone_key(const struct uuid *key, const char *type);
const char *default_nb_db(void);
const char *default_sb_db(void);
struct ovsdb_idl_table_class;
const char *db_table_usage(struct ds *tables,
const struct ovsdb_idl_table_class *class,
int n_tables);
bool ovn_is_known_nb_lsp_type(const char *type);
uint32_t sbrec_logical_flow_hash(const struct sbrec_logical_flow *);
......
......@@ -820,64 +820,11 @@
additional ways to identify records. Some commands also take
<var>column</var> parameters that identify a particular field within the
records in a table.</p>
<p>The following tables are currently defined:</p>
<dl>
<dt><code>Logical_Switch</code></dt>
<dd>
An L2 logical switch. Records may be identified by name.
</dd>
<dt><code>Logical_Switch_Port</code></dt>
<dd>
A port within an L2 logical switch. Records may be identified by name.
</dd>
<dt><code>ACL</code></dt>
<dd>
An ACL rule for a logical switch that points to it through its <var>acls</var> column.
</dd>
<dt><code>Logical_Router</code></dt>
<dd>
An L3 logical router. Records may be identified by name.
</dd>
<dt><code>Logical_Router_Port</code></dt>
<dd>
A port within an L3 logical router. Records may be identified by name.
</dd>
<dt><code>Logical_Router_Static_Route</code></dt>
<dd>
A static route belonging to an L3 logical router.
</dd>
<dt><code>Address_Set</code></dt>
<dd>
An address set that can be used in ACLs.
</dd>
<dt><code>Load_Balancer</code></dt>
<dd>
A load balancer for a logical switch that points to it through its <var>load_balancer</var> column.
</dd>
<dt><code>NAT</code></dt>
<dd>
A NAT rule for a Gateway router.
</dd>
<dt><code>DHCP_Options</code></dt>
<dd>
DHCP options.
</dd>
<dt><code>NB_Global</code></dt>
<dd>
North bound global configurations.
</dd>
</dl>
<p>
For a list of tables and their columns, see <code>ovn-nb</code>(5) or
see the table listing from the <code>--help</code> option.
</p>
<p>
Record names must be specified in full and with correct capitalization,
......
......@@ -455,6 +455,7 @@ SSL commands:\n\
set the SSL configuration\n\
\n\
%s\
%s\
\n\
Synchronization command (use with --wait=sb|hv):\n\
sync wait even for earlier changes to take effect\n\
......@@ -469,7 +470,7 @@ Options:\n\
--dry-run do not commit changes to database\n\
--oneline print exactly one line of output per command\n",
program_name, program_name, ctl_get_db_cmd_usage(),
default_nb_db());
ctl_list_db_tables_usage(), default_nb_db());
table_usage();
vlog_usage();
printf("\
......@@ -4081,6 +4082,6 @@ static const struct ctl_command_syntax nbctl_commands[] = {
static void
nbctl_cmd_init(void)
{
ctl_init(nbrec_table_classes, tables, NULL, nbctl_exit);
ctl_init(&nbrec_idl_class, nbrec_table_classes, tables, NULL, nbctl_exit);
ctl_register_commands(nbctl_commands);
}
......@@ -278,8 +278,9 @@ parameter may be the UUID for a record, and many tables offer
additional ways to identify records. Some commands also take
\fIcolumn\fR parameters that identify a particular field within the
records in a table.
.\" It would be kind to list all the tables and their supported identifiers
.\" here.
.PP
For a list of tables and their columns, see \fBovn\-sb\fR(5) or
see the table listing from the \fB--help\fR option.
.PP
Record names must be specified in full and with correct
capitalization, except that UUIDs may be abbreviated to their first 4
......
......@@ -326,6 +326,7 @@ SSL commands:\n\
set the SSL configuration\n\
\n\
%s\
%s\
\n\
Options:\n\
--db=DATABASE connect to DATABASE\n\
......@@ -334,7 +335,7 @@ Options:\n\
--dry-run do not commit changes to database\n\
--oneline print exactly one line of output per command\n",
program_name, program_name, ctl_get_db_cmd_usage(),
default_sb_db());
ctl_list_db_tables_usage(), default_sb_db());
table_usage();
vlog_usage();
printf("\
......@@ -1442,6 +1443,7 @@ static const struct ctl_command_syntax sbctl_commands[] = {
static void
sbctl_cmd_init(void)
{
ctl_init(sbrec_table_classes, tables, cmd_show_tables, sbctl_exit);
ctl_init(&sbrec_idl_class, sbrec_table_classes, tables,
cmd_show_tables, sbctl_exit);
ctl_register_commands(sbctl_commands);
}
......@@ -530,55 +530,8 @@ additional ways to identify records. Some commands also take
\fIcolumn\fR parameters that identify a particular field within the
records in a table.
.PP
The following tables are currently defined:
.IP "\fBOpen_vSwitch\fR"
Global configuration for an \fBovs\-vswitchd\fR. This table contains
exactly one record, identified by specifying \fB.\fR as the record
name.
.IP "\fBBridge\fR"
Configuration for a bridge within an Open vSwitch. Records may be
identified by bridge name.
.IP "\fBPort\fR"
A bridge port. Records may be identified by port name.
.IP "\fBInterface\fR"
A network device attached to a port. Records may be identified by
name.
.IP "\fBFlow_Table\fR"
Configuration for a particular OpenFlow flow table. Records may be
identified by name.
.IP "\fBQoS\fR"
Quality-of-service configuration for a \fBPort\fR. Records may be
identified by port name.
.IP "\fBQueue\fR"
Configuration for one queue within a \fBQoS\fR configuration. Records
may only be identified by UUID.
.IP "\fBMirror\fR"
A port mirroring configuration attached to a bridge. Records may be
identified by mirror name.
.IP "\fBController\fR"
Configuration for an OpenFlow controller. A controller attached to a
particular bridge may be identified by the bridge's name.
.IP "\fBManager\fR"
Configuration for an OVSDB connection. Records may be identified
by target (e.g. \fBtcp:1.2.3.4\fR).
.IP "\fBNetFlow\fR"
A NetFlow configuration attached to a bridge. Records may be
identified by bridge name.
.IP "\fBSSL\fR"
The global SSL configuration for \fBovs\-vswitchd\fR. The record
attached to the \fBOpen_vSwitch\fR table may be identified by
specifying \fB.\fR as the record name.
.IP "\fBsFlow\fR"
An sFlow exporter configuration attached to a bridge. Records may be
identified by bridge name.
.IP "\fBIPFIX\fR"
An IPFIX exporter configuration attached to a bridge. Records may be
identified by bridge name.
.IP "\fBFlow_Sample_Collector_Set\fR"
An IPFIX exporter configuration attached to a bridge for sampling
packets on a per-flow basis using OpenFlow \fBsample\fR actions.
.IP "\fBAutoAttach\fR"
Configuration for Auto Attach within a bridge.
For a list of tables and their columns, see \fBovs-vswitchd.conf.db\fR(5) or
see the table listing from the \fB--help\fR option.
.PP
Record names must be specified in full and with correct
capitalization, except that UUIDs may be abbreviated to their first 4
......
......@@ -416,6 +416,7 @@ Switch commands:\n\
emer-reset reset switch to known good state\n\
\n\
%s\
%s\
\n\
Options:\n\
--db=DATABASE connect to DATABASE\n\
......@@ -425,7 +426,8 @@ Options:\n\
-t, --timeout=SECS wait at most SECS seconds for ovs-vswitchd\n\
--dry-run do not commit changes to database\n\
--oneline print exactly one line of output per command\n",
program_name, program_name, ctl_get_db_cmd_usage(), ctl_default_db());
program_name, program_name, ctl_get_db_cmd_usage(),
ctl_list_db_tables_usage(), ctl_default_db());
table_usage();
vlog_usage();
printf("\
......@@ -2877,6 +2879,7 @@ static const struct ctl_command_syntax vsctl_commands[] = {
static void
vsctl_cmd_init(void)
{
ctl_init(ovsrec_table_classes, tables, cmd_show_tables, vsctl_exit);
ctl_init(&ovsrec_idl_class, ovsrec_table_classes, tables, cmd_show_tables,
vsctl_exit);
ctl_register_commands(vsctl_commands);
}
......@@ -361,6 +361,7 @@ MAC binding commands:\n\
list-remote-macs LS list remote mac entries\n\
\n\
%s\
%s\
\n\
Options:\n\
--db=DATABASE connect to DATABASE\n\
......@@ -368,7 +369,8 @@ Options:\n\
-t, --timeout=SECS wait at most SECS seconds\n\
--dry-run do not commit changes to database\n\
--oneline print exactly one line of output per command\n",
program_name, program_name, ctl_get_db_cmd_usage(), ctl_default_db());
program_name, program_name, ctl_get_db_cmd_usage(),
ctl_list_db_tables_usage(), ctl_default_db());
table_usage();
vlog_usage();
printf("\
......@@ -2499,6 +2501,7 @@ static const struct ctl_command_syntax vtep_commands[] = {
static void
vtep_ctl_cmd_init(void)
{
ctl_init(vteprec_table_classes, tables, cmd_show_tables, vtep_ctl_exit);
ctl_init(&vteprec_idl_class, vteprec_table_classes, tables,
cmd_show_tables, vtep_ctl_exit);
ctl_register_commands(vtep_commands);
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment