Skip to content

I
iproute2
Commit cbec0219 authored by David Ward's avatar David Ward Committed by Stephen Hemminger
Browse files
Options

xfrm: Update documentation 

The ip(8) man page and the "ip xfrm [ XFRM-OBJECT ] help" command output
are updated to include missing options, fix errors, and improve grammar.
There are no functional changes made.

The documentation for the ip command has many different meanings for the
same formatting symbols (which really needs to be fixed). This patch makes
consistent use of brackets [ ] to indicate optional parameters, pipes | to
mean "OR", braces { } to group things together, and dashes - instead of
underscores _ inside of parameter names. The parameters are listed in the
order in which they are parsed in the source code.

There are several parameters and options that are still not mentioned or
need to be described more thoroughly in the "COMMAND SYNTAX" section of
the ip(8) man page. I would appreciate help from the developers with this.
Signed-off-by: default avatarDavid Ward <david.ward@ll.mit.edu>
parent 4f69c63a
Expand all Show whitespace changes
Inline Side-by-side
Showing with 515 additions and 438 deletions
ip/ipxfrm.c
View file @ cbec0219
......@@ -59,8 +59,8 @@ static void usage(void) __attribute__((noreturn));
static void usage(void)
{
fprintf(stderr,
"Usage: ip xfrm XFRM_OBJECT { COMMAND | help }\n"
"where XFRM_OBJECT := { state | policy | monitor }\n");
"Usage: ip xfrm XFRM-OBJECT { COMMAND | help }\n"
"where XFRM-OBJECT := state | policy | monitor\n");
exit(-1);
}
......@@ -1040,7 +1040,7 @@ int xfrm_id_parse(xfrm_address_t *saddr, struct xfrm_id *id, __u16 *family,
ret = xfrm_xfrmproto_getbyname(*argv);
if (ret < 0)
invarg("\"XFRM_PROTO\" is invalid", *argv);
invarg("\"XFRM-PROTO\" is invalid", *argv);
id->proto = (__u8)ret;
......@@ -1072,7 +1072,7 @@ int xfrm_id_parse(xfrm_address_t *saddr, struct xfrm_id *id, __u16 *family,
invarg("the same address family is required between \"src\" and \"dst\"", *argv);
if (loose == 0 && id->proto == 0)
missarg("XFRM_PROTO");
missarg("XFRM-PROTO");
if (argc == *argcp)
missarg("ID");
......
ip/xfrm_monitor.c
View file @ cbec0219
......@@ -37,7 +37,7 @@ static void usage(void) __attribute__((noreturn));
static void usage(void)
{
fprintf(stderr, "Usage: ip xfrm monitor [ all | LISTofOBJECTS ]\n");
fprintf(stderr, "Usage: ip xfrm monitor [ all | LISTofXFRM-OBJECTS ]\n");
exit(-1);
}
......
ip/xfrm_policy.c
View file @ cbec0219
......@@ -54,50 +54,50 @@ static void usage(void) __attribute__((noreturn));
static void usage(void)
{
fprintf(stderr, "Usage: ip xfrm policy { add | update } dir DIR SELECTOR [ ctx SEC_CTX ][ index INDEX ] [ ptype PTYPE ]\n");
fprintf(stderr, " [ action ACTION ] [ priority PRIORITY ] [ flag FLAG-LIST ] [ LIMIT-LIST ] [ TMPL-LIST ] [mark MARK [mask MASK]]\n");
fprintf(stderr, "Usage: ip xfrm policy { delete | get } dir DIR [ SELECTOR | index INDEX ] [ ctx SEC_CTX ][ ptype PTYPE ] [mark MARK [mask MASK]]\n");
fprintf(stderr, "Usage: ip xfrm policy { deleteall | list } [ dir DIR ] [ SELECTOR ]\n");
fprintf(stderr, " [ index INDEX ] [ action ACTION ] [ priority PRIORITY ] [ flag FLAG-LIST ]\n");
fprintf(stderr, "Usage: ip xfrm policy { add | update } SELECTOR dir DIR [ ctx CTX ]\n");
fprintf(stderr, " [ mark MARK [ mask MASK ] ] [ index INDEX ] [ ptype PTYPE ]\n");
fprintf(stderr, " [ action ACTION ] [ priority PRIORITY ] [ flag FLAG-LIST ]\n");
fprintf(stderr, " [ LIMIT-LIST ] [ TMPL-LIST ]\n");
fprintf(stderr, "Usage: ip xfrm policy { delete | get } { SELECTOR | index INDEX } dir DIR\n");
fprintf(stderr, " [ ctx CTX ] [ mark MARK [ mask MASK ] ] [ ptype PTYPE ]\n");
fprintf(stderr, "Usage: ip xfrm policy { deleteall | list } [ SELECTOR ] [ dir DIR ]\n");
fprintf(stderr, " [ index INDEX ] [ ptype PTYPE ] [ action ACTION ] [ priority PRIORITY ]\n");
fprintf(stderr, " [ flag FLAG-LIST ]\n");
fprintf(stderr, "Usage: ip xfrm policy flush [ ptype PTYPE ]\n");
fprintf(stderr, "Usage: ip xfrm count\n");
fprintf(stderr, "PTYPE := [ main | sub ](default=main)\n");
fprintf(stderr, "DIR := [ in | out | fwd ]\n");
fprintf(stderr, "SELECTOR := src ADDR[/PLEN] dst ADDR[/PLEN] [ UPSPEC ] [ dev DEV ]\n");
fprintf(stderr, "UPSPEC := proto PROTO [ [ sport PORT ] [ dport PORT ] |\n");
fprintf(stderr, " [ type NUMBER ] [ code NUMBER ] |\n");
fprintf(stderr, " [ key { DOTTED_QUAD | NUMBER } ] ]\n");
//fprintf(stderr, "DEV - device name(default=none)\n");
fprintf(stderr, "ACTION := [ allow | block ](default=allow)\n");
//fprintf(stderr, "PRIORITY - priority value(default=0)\n");
fprintf(stderr, "SELECTOR := [ src ADDR[/PLEN] ] [ dst ADDR[/PLEN] ] [ dev DEV ] [ UPSPEC ]\n");
fprintf(stderr, "UPSPEC := proto { { ");
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_TCP));
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_UDP));
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_SCTP));
fprintf(stderr, "%s", strxf_proto(IPPROTO_DCCP));
fprintf(stderr, " } [ sport PORT ] [ dport PORT ] |\n");
fprintf(stderr, " { ");
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_ICMP));
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_ICMPV6));
fprintf(stderr, "%s", strxf_proto(IPPROTO_MH));
fprintf(stderr, " } [ type NUMBER ] [ code NUMBER ] |\n");
fprintf(stderr, " %s", strxf_proto(IPPROTO_GRE));
fprintf(stderr, " [ key { DOTTED-QUAD | NUMBER } ] | PROTO }\n");
fprintf(stderr, "DIR := in | out | fwd\n");
fprintf(stderr, "PTYPE := main | sub\n");
fprintf(stderr, "ACTION := allow | block\n");
fprintf(stderr, "FLAG-LIST := [ FLAG-LIST ] FLAG\n");
fprintf(stderr, "FLAG := [ localok | icmp ]\n");
fprintf(stderr, "LIMIT-LIST := [ LIMIT-LIST ] | [ limit LIMIT ]\n");
fprintf(stderr, "LIMIT := [ [time-soft|time-hard|time-use-soft|time-use-hard] SECONDS ] |\n");
fprintf(stderr, " [ [byte-soft|byte-hard] SIZE ] | [ [packet-soft|packet-hard] NUMBER ]\n");
fprintf(stderr, "TMPL-LIST := [ TMPL-LIST ] | [ tmpl TMPL ]\n");
fprintf(stderr, "FLAG := localok | icmp\n");
fprintf(stderr, "LIMIT-LIST := [ LIMIT-LIST ] limit LIMIT\n");
fprintf(stderr, "LIMIT := { time-soft | time-hard | time-use-soft | time-use-hard } SECONDS |\n");
fprintf(stderr, " { byte-soft | byte-hard } SIZE | { packet-soft | packet-hard } COUNT\n");
fprintf(stderr, "TMPL-LIST := [ TMPL-LIST ] tmpl TMPL\n");
fprintf(stderr, "TMPL := ID [ mode MODE ] [ reqid REQID ] [ level LEVEL ]\n");
fprintf(stderr, "ID := [ src ADDR ] [ dst ADDR ] [ proto XFRM_PROTO ] [ spi SPI ]\n");
fprintf(stderr, "XFRM_PROTO := [ ");
fprintf(stderr, "ID := [ src ADDR ] [ dst ADDR ] [ proto XFRM-PROTO ] [ spi SPI ]\n");
fprintf(stderr, "XFRM-PROTO := ");
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_ESP));
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_AH));
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_COMP));
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_ROUTING));
fprintf(stderr, "%s ", strxf_xfrmproto(IPPROTO_DSTOPTS));
fprintf(stderr, "]\n");
fprintf(stderr, "MODE := [ transport | tunnel | beet ](default=transport)\n");
//fprintf(stderr, "REQID - number(default=0)\n");
fprintf(stderr, "LEVEL := [ required | use ](default=required)\n");
fprintf(stderr, "%s\n", strxf_xfrmproto(IPPROTO_DSTOPTS));
fprintf(stderr, "MODE := transport | tunnel | ro | in_trigger | beet\n");
fprintf(stderr, "LEVEL := required | use\n");
exit(-1);
}
......
ip/xfrm_state.c
View file @ cbec0219
......@@ -56,63 +56,57 @@ static void usage(void) __attribute__((noreturn));
static void usage(void)
{
fprintf(stderr, "Usage: ip xfrm state { add | update } ID [ XFRM_OPT ] [ ctx SEC_CTX ] [ mode MODE ]\n");
fprintf(stderr, " [ reqid REQID ] [ seq SEQ ] [ replay-window SIZE ] [ flag FLAG-LIST ]\n");
fprintf(stderr, " [ encap ENCAP ] [ sel SELECTOR ] [ replay-seq SEQ ]\n");
fprintf(stderr, " [ replay-oseq SEQ ] [ LIMIT-LIST ]\n");
fprintf(stderr, "Usage: ip xfrm state allocspi ID [ mode MODE ] [ reqid REQID ] [ seq SEQ ]\n");
fprintf(stderr, " [ min SPI max SPI ]\n");
fprintf(stderr, "Usage: ip xfrm state { delete | get } ID\n");
fprintf(stderr, "Usage: ip xfrm state { add | update } ID [ ALGO-LIST ] [ mode MODE ]\n");
fprintf(stderr, " [ mark MARK [ mask MASK ] ] [ reqid REQID ] [ seq SEQ ]\n");
fprintf(stderr, " [ replay-window SIZE ] [ replay-seq SEQ ] [ replay-oseq SEQ ]\n");
fprintf(stderr, " [ flag FLAG-LIST ] [ sel SELECTOR ] [ LIMIT-LIST ] [ encap ENCAP ]\n");
fprintf(stderr, " [ coa ADDR[/PLEN] ] [ ctx CTX ]\n");
fprintf(stderr, "Usage: ip xfrm state allocspi ID [ mode MODE ] [ mark MARK [ mask MASK ] ]\n");
fprintf(stderr, " [ reqid REQID ] [ seq SEQ ] [ min SPI max SPI ]\n");
fprintf(stderr, "Usage: ip xfrm state { delete | get } ID [ mark MARK [ mask MASK ] ]\n");
fprintf(stderr, "Usage: ip xfrm state { deleteall | list } [ ID ] [ mode MODE ] [ reqid REQID ]\n");
fprintf(stderr, " [ flag FLAG-LIST ]\n");
fprintf(stderr, "Usage: ip xfrm state flush [ proto XFRM_PROTO ]\n");
fprintf(stderr, "Usage: ip xfrm state count \n");
fprintf(stderr, "ID := [ src ADDR ] [ dst ADDR ] [ proto XFRM_PROTO ] [ spi SPI ] [mark MARK [mask MASK]]\n");
//fprintf(stderr, "XFRM_PROTO := [ esp | ah | comp ]\n");
fprintf(stderr, "XFRM_PROTO := [ ");
fprintf(stderr, "Usage: ip xfrm state flush [ proto XFRM-PROTO ]\n");
fprintf(stderr, "Usage: ip xfrm state count\n");
fprintf(stderr, "ID := [ src ADDR ] [ dst ADDR ] [ proto XFRM-PROTO ] [ spi SPI ]\n");
fprintf(stderr, "XFRM-PROTO := ");
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_ESP));
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_AH));
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_COMP));
fprintf(stderr, "%s | ", strxf_xfrmproto(IPPROTO_ROUTING));
fprintf(stderr, "%s ", strxf_xfrmproto(IPPROTO_DSTOPTS));
fprintf(stderr, "]\n");
//fprintf(stderr, "SPI - security parameter index(default=0)\n");
fprintf(stderr, "MODE := [ transport | tunnel | ro | beet ](default=transport)\n");
//fprintf(stderr, "REQID - number(default=0)\n");
fprintf(stderr, "FLAG-LIST := [ FLAG-LIST ] FLAG\n");
fprintf(stderr, "FLAG := [ noecn | decap-dscp | nopmtudisc | wildrecv | icmp | af-unspec | align4 ]\n");
fprintf(stderr, "ENCAP := ENCAP-TYPE SPORT DPORT OADDR\n");
fprintf(stderr, "ENCAP-TYPE := espinudp | espinudp-nonike\n");
fprintf(stderr, "ALGO-LIST := [ ALGO-LIST ] | [ ALGO ]\n");
fprintf(stderr, "ALGO := ALGO_TYPE ALGO_NAME ALGO_KEY "
"[ ALGO_ICV_LEN | ALGO_TRUNC_LEN ]\n");
fprintf(stderr, "ALGO_TYPE := [ ");
fprintf(stderr, "%s | ", strxf_algotype(XFRMA_ALG_AEAD));
fprintf(stderr, "%s\n", strxf_xfrmproto(IPPROTO_DSTOPTS));
fprintf(stderr, "ALGO-LIST := [ ALGO-LIST ] ALGO\n");
fprintf(stderr, "ALGO := { ");
fprintf(stderr, "%s | ", strxf_algotype(XFRMA_ALG_CRYPT));
fprintf(stderr, "%s | ", strxf_algotype(XFRMA_ALG_AUTH));
fprintf(stderr, "%s | ", strxf_algotype(XFRMA_ALG_AUTH_TRUNC));
fprintf(stderr, "%s ", strxf_algotype(XFRMA_ALG_COMP));
fprintf(stderr, "]\n");
//fprintf(stderr, "ALGO_NAME - algorithm name\n");
//fprintf(stderr, "ALGO_KEY - algorithm key\n");
fprintf(stderr, "SELECTOR := src ADDR[/PLEN] dst ADDR[/PLEN] [ UPSPEC ] [ dev DEV ]\n");
fprintf(stderr, "UPSPEC := proto PROTO [ [ sport PORT ] [ dport PORT ] |\n");
fprintf(stderr, " [ type NUMBER ] [ code NUMBER ] ]\n");
fprintf(stderr, "%s", strxf_algotype(XFRMA_ALG_COMP));
fprintf(stderr, " } ALGO-NAME ALGO-KEY |\n");
fprintf(stderr, " %s", strxf_algotype(XFRMA_ALG_AEAD));
fprintf(stderr, " ALGO-NAME ALGO-KEY ALGO-ICV-LEN |\n");
fprintf(stderr, " %s", strxf_algotype(XFRMA_ALG_AUTH_TRUNC));
fprintf(stderr, " ALGO-NAME ALGO-KEY ALGO-TRUNC-LEN\n");
fprintf(stderr, "MODE := transport | tunnel | ro | in_trigger | beet\n");
fprintf(stderr, "FLAG-LIST := [ FLAG-LIST ] FLAG\n");
fprintf(stderr, "FLAG := noecn | decap-dscp | nopmtudisc | wildrecv | icmp | af-unspec | align4\n");
fprintf(stderr, "SELECTOR := [ src ADDR[/PLEN] ] [ dst ADDR[/PLEN] ] [ dev DEV ] [ UPSPEC ]\n");
fprintf(stderr, "UPSPEC := proto { { ");
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_TCP));
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_UDP));
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_SCTP));
fprintf(stderr, "%s", strxf_proto(IPPROTO_DCCP));
fprintf(stderr, " } [ sport PORT ] [ dport PORT ] |\n");
fprintf(stderr, " { ");
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_ICMP));
fprintf(stderr, "%s | ", strxf_proto(IPPROTO_ICMPV6));
fprintf(stderr, "%s", strxf_proto(IPPROTO_MH));
fprintf(stderr, " } [ type NUMBER ] [ code NUMBER ] |\n");
fprintf(stderr, " %s", strxf_proto(IPPROTO_GRE));
fprintf(stderr, " [ key { DOTTED-QUAD | NUMBER } ] | PROTO }\n");
fprintf(stderr, "LIMIT-LIST := [ LIMIT-LIST ] limit LIMIT\n");
fprintf(stderr, "LIMIT := { time-soft | time-hard | time-use-soft | time-use-hard } SECONDS |\n");
fprintf(stderr, " { byte-soft | byte-hard } SIZE | { packet-soft | packet-hard } COUNT\n");
fprintf(stderr, "ENCAP := { espinudp | espinudp-nonike } SPORT DPORT OADDR\n");
//fprintf(stderr, "DEV - device name(default=none)\n");
fprintf(stderr, "LIMIT-LIST := [ LIMIT-LIST ] | [ limit LIMIT ]\n");
fprintf(stderr, "LIMIT := [ [time-soft|time-hard|time-use-soft|time-use-hard] SECONDS ] |\n");
fprintf(stderr, " [ [byte-soft|byte-hard] SIZE ] | [ [packet-soft|packet-hard] COUNT ]\n");
exit(-1);
}
......@@ -124,7 +118,7 @@ static int xfrm_algo_parse(struct xfrm_algo *alg, enum xfrm_attr_type_t type,
#if 0
/* XXX: verifying both name and key is required! */
fprintf(stderr, "warning: ALGONAME/ALGOKEY will send to kernel promiscuously!(verifying them isn't implemented yet)\n");
fprintf(stderr, "warning: ALGO-NAME/ALGO-KEY will send to kernel promiscuously! (verifying them isn't implemented yet)\n");
#endif
strncpy(alg->alg_name, name, sizeof(alg->alg_name));
......@@ -144,7 +138,7 @@ static int xfrm_algo_parse(struct xfrm_algo *alg, enum xfrm_attr_type_t type,
/* calculate length of the converted values(real key) */
len = (plen + 1) / 2;
if (len > max)
invarg("\"ALGOKEY\" makes buffer overflow\n", key);
invarg("\"ALGO-KEY\" makes buffer overflow\n", key);
for (i = - (plen % 2), j = 0; j < len; i += 2, j++) {
char vbuf[3];
......@@ -155,7 +149,7 @@ static int xfrm_algo_parse(struct xfrm_algo *alg, enum xfrm_attr_type_t type,
vbuf[2] = '\0';
if (get_u8(&val, vbuf, 16))
invarg("\"ALGOKEY\" is invalid", key);
invarg("\"ALGO-KEY\" is invalid", key);
buf[j] = val;
}
......@@ -163,7 +157,7 @@ static int xfrm_algo_parse(struct xfrm_algo *alg, enum xfrm_attr_type_t type,
len = slen;
if (len > 0) {
if (len > max)
invarg("\"ALGOKEY\" makes buffer overflow\n", key);
invarg("\"ALGO-KEY\" makes buffer overflow\n", key);
strncpy(buf, key, len);
}
......@@ -384,37 +378,37 @@ static int xfrm_state_modify(int cmd, unsigned flags, int argc, char **argv)
switch (type) {
case XFRMA_ALG_AEAD:
if (aeadop)
duparg("ALGOTYPE", *argv);
duparg("ALGO-TYPE", *argv);
aeadop = *argv;
break;
case XFRMA_ALG_CRYPT:
if (ealgop)
duparg("ALGOTYPE", *argv);
duparg("ALGO-TYPE", *argv);
ealgop = *argv;
break;
case XFRMA_ALG_AUTH:
case XFRMA_ALG_AUTH_TRUNC:
if (aalgop)
duparg("ALGOTYPE", *argv);
duparg("ALGO-TYPE", *argv);
aalgop = *argv;
break;
case XFRMA_ALG_COMP:
if (calgop)
duparg("ALGOTYPE", *argv);
duparg("ALGO-TYPE", *argv);
calgop = *argv;
break;
default:
/* not reached */
invarg("\"ALGOTYPE\" is invalid\n", *argv);
invarg("\"ALGO-TYPE\" is invalid\n", *argv);
}
if (!NEXT_ARG_OK())
missarg("ALGONAME");
missarg("ALGO-NAME");
NEXT_ARG();
name = *argv;
if (!NEXT_ARG_OK())
missarg("ALGOKEY");
missarg("ALGO-KEY");
NEXT_ARG();
key = *argv;
......@@ -424,7 +418,7 @@ static int xfrm_state_modify(int cmd, unsigned flags, int argc, char **argv)
switch (type) {
case XFRMA_ALG_AEAD:
if (!NEXT_ARG_OK())
missarg("ALGOICVLEN");
missarg("ALGO-ICV-LEN");
NEXT_ARG();
if (get_u32(&icvlen, *argv, 0))
invarg("\"aead\" ICV length is invalid",
......@@ -436,7 +430,7 @@ static int xfrm_state_modify(int cmd, unsigned flags, int argc, char **argv)
break;
case XFRMA_ALG_AUTH_TRUNC:
if (!NEXT_ARG_OK())
missarg("ALGOTRUNCLEN");
missarg("ALGO-TRUNC-LEN");
NEXT_ARG();
if (get_u32(&trunclen, *argv, 0))
invarg("\"auth\" trunc length is invalid",
......@@ -649,7 +643,7 @@ static int xfrm_state_allocspi(int argc, char **argv)
exit(1);
}
if (req.xspi.min > req.xspi.max) {
fprintf(stderr, "\"min\" valie is larger than \"max\" one\n");
fprintf(stderr, "\"min\" value is larger than \"max\" value\n");
exit(1);
}
} else {
......@@ -1164,7 +1158,7 @@ static int xfrm_state_flush(int argc, char **argv)
ret = xfrm_xfrmproto_getbyname(*argv);
if (ret < 0)
invarg("\"XFRM_PROTO\" is invalid", *argv);
invarg("\"XFRM-PROTO\" is invalid", *argv);
req.xsf.proto = (__u8)ret;
} else
......
man/man8/ip.8
View file @ cbec0219
This diff is collapsed.
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7