man/man8/ip-xfrm.8

   1 .TH IP\-XFRM 8 "20 Dec 2011" "iproute2" "Linux"
   2 .SH "NAME"
   3 ip-xfrm \- transform configuration
   4 .SH "SYNOPSIS"
   5 .sp
   6 .ad l
   7 .in +8
   8 .ti -8
   9 .B ip
  10 .RI "[ " OPTIONS " ]"
  11 .B xfrm
  12 .RI " { " COMMAND " | "
  13 .BR help " }"
  14 .sp
  15
  16 .ti -8
  17 .B "ip xfrm"
  18 .IR XFRM-OBJECT " { " COMMAND " | "
  19 .BR help " }"
  20 .sp
  21
  22 .ti -8
  23 .IR XFRM-OBJECT " :="
  24 .BR state " | " policy " | " monitor
  25 .sp
  26
  27 .ti -8
  28 .BR "ip xfrm state" " { " add " | " update " } "
  29 .IR ID " [ " ALGO-LIST " ]"
  30 .RB "[ " mode
  31 .IR MODE " ]"
  32 .RB "[ " mark
  33 .I MARK
  34 .RB "[ " mask
  35 .IR MASK " ] ]"
  36 .RB "[ " reqid
  37 .IR REQID " ]"
  38 .RB "[ " seq
  39 .IR SEQ " ]"
  40 .RB "[ " replay-window
  41 .IR SIZE " ]"
  42 .RB "[ " replay-seq
  43 .IR SEQ " ]"
  44 .RB "[ " replay-oseq
  45 .IR SEQ " ]"
  46 .RB "[ " replay-seq-hi
  47 .IR SEQ " ]"
  48 .RB "[ " replay-oseq-hi
  49 .IR SEQ " ]"
  50 .RB "[ " flag
  51 .IR FLAG-LIST " ]"
  52 .RB "[ " sel
  53 .IR SELECTOR " ] [ " LIMIT-LIST " ]"
  54 .RB "[ " encap
  55 .IR ENCAP " ]"
  56 .RB "[ " coa
  57 .IR ADDR "[/" PLEN "] ]"
  58 .RB "[ " ctx
  59 .IR CTX " ]"
  60 .RB "[ " extra-flag
  61 .IR EXTRA-FLAG-LIST " ]"
  62
  63 .ti -8
  64 .B "ip xfrm state allocspi"
  65 .I ID
  66 .RB "[ " mode
  67 .IR MODE " ]"
  68 .RB "[ " mark
  69 .I MARK
  70 .RB "[ " mask
  71 .IR MASK " ] ]"
  72 .RB "[ " reqid
  73 .IR REQID " ]"
  74 .RB "[ " seq
  75 .IR SEQ " ]"
  76 .RB "[ " min
  77 .I SPI
  78 .B max
  79 .IR SPI " ]"
  80
  81 .ti -8
  82 .BR "ip xfrm state" " { " delete " | " get " } "
  83 .I ID
  84 .RB "[ " mark
  85 .I MARK
  86 .RB "[ " mask
  87 .IR MASK " ] ]"
  88
  89 .ti -8
  90 .BR "ip xfrm state" " { " deleteall " | " list " } ["
  91 .IR ID " ]"
  92 .RB "[ " mode
  93 .IR MODE " ]"
  94 .RB "[ " reqid
  95 .IR REQID " ]"
  96 .RB "[ " flag
  97 .IR FLAG-LIST " ]"
  98
  99 .ti -8
 100 .BR "ip xfrm state flush" " [ " proto
 101 .IR XFRM-PROTO " ]"
 102
 103 .ti -8
 104 .BR "ip xfrm state count"
 105
 106 .ti -8
 107 .IR ID " :="
 108 .RB "[ " src
 109 .IR ADDR " ]"
 110 .RB "[ " dst
 111 .IR ADDR " ]"
 112 .RB "[ " proto
 113 .IR XFRM-PROTO " ]"
 114 .RB "[ " spi
 115 .IR SPI " ]"
 116
 117 .ti -8
 118 .IR XFRM-PROTO " :="
 119 .BR esp " | " ah " | " comp " | " route2 " | " hao
 120
 121 .ti -8
 122 .IR ALGO-LIST " := [ " ALGO-LIST " ] " ALGO
 123
 124 .ti -8
 125 .IR ALGO " :="
 126 .RB "{ " enc " | " auth " } "
 127 .IR ALGO-NAME " " ALGO-KEYMAT " |"
 128 .br
 129 .B auth-trunc
 130 .IR ALGO-NAME " " ALGO-KEYMAT " " ALGO-TRUNC-LEN " |"
 131 .br
 132 .B aead
 133 .IR ALGO-NAME " " ALGO-KEYMAT " " ALGO-ICV-LEN " |"
 134 .br
 135 .B comp
 136 .IR ALGO-NAME
 137
 138 .ti -8
 139 .IR MODE " := "
 140 .BR transport " | " tunnel " | " beet " | " ro " | " in_trigger
 141
 142 .ti -8
 143 .IR FLAG-LIST " := [ " FLAG-LIST " ] " FLAG
 144
 145 .ti -8
 146 .IR FLAG " :="
 147 .BR noecn " | " decap-dscp " | " nopmtudisc " | " wildrecv " | " icmp " | "
 148 .BR af-unspec " | " align4 " | " esn
 149
 150 .ti -8
 151 .IR SELECTOR " :="
 152 .RB "[ " src
 153 .IR ADDR "[/" PLEN "] ]"
 154 .RB "[ " dst
 155 .IR ADDR "[/" PLEN "] ]"
 156 .RB "[ " dev
 157 .IR DEV " ]"
 158 .br
 159 .RI "[ " UPSPEC " ]"
 160
 161 .ti -8
 162 .IR UPSPEC " := "
 163 .BR proto " {"
 164 .IR PROTO " |"
 165 .br
 166 .RB "{ " tcp " | " udp " | " sctp " | " dccp " } [ " sport
 167 .IR PORT " ]"
 168 .RB "[ " dport
 169 .IR PORT " ] |"
 170 .br
 171 .RB "{ " icmp " | " ipv6-icmp " | " mobility-header " } [ " type
 172 .IR NUMBER " ]"
 173 .RB "[ " code
 174 .IR NUMBER " ] |"
 175 .br
 176 .BR gre " [ " key
 177 .RI "{ " DOTTED-QUAD " | " NUMBER " } ] }"
 178
 179 .ti -8
 180 .IR LIMIT-LIST " := [ " LIMIT-LIST " ]"
 181 .B limit
 182 .I LIMIT
 183
 184 .ti -8
 185 .IR LIMIT " :="
 186 .RB "{ " time-soft " | " time-hard " | " time-use-soft " | " time-use-hard " }"
 187 .IR "SECONDS" " |"
 188 .br
 189 .RB "{ " byte-soft " | " byte-hard " }"
 190 .IR SIZE " |"
 191 .br
 192 .RB "{ " packet-soft " | " packet-hard " }"
 193 .I COUNT
 194
 195 .ti -8
 196 .IR ENCAP " :="
 197 .RB "{ " espinudp " | " espinudp-nonike " }"
 198 .IR SPORT " " DPORT " " OADDR
 199
 200 .ti -8
 201 .IR EXTRA-FLAG-LIST " := [ " EXTRA-FLAG-LIST " ] " EXTRA-FLAG
 202
 203 .ti -8
 204 .IR EXTRA-FLAG " := "
 205 .B dont-encap-dscp
 206
 207 .ti -8
 208 .BR "ip xfrm policy" " { " add " | " update " }"
 209 .I SELECTOR
 210 .B dir
 211 .I DIR
 212 .RB "[ " ctx
 213 .IR CTX " ]"
 214 .RB "[ " mark
 215 .I MARK
 216 .RB "[ " mask
 217 .IR MASK " ] ]"
 218 .RB "[ " index
 219 .IR INDEX " ]"
 220 .RB "[ " ptype
 221 .IR PTYPE " ]"
 222 .RB "[ " action
 223 .IR ACTION " ]"
 224 .RB "[ " priority
 225 .IR PRIORITY " ]"
 226 .RB "[ " flag
 227 .IR FLAG-LIST " ]"
 228 .RI "[ " LIMIT-LIST " ] [ " TMPL-LIST " ]"
 229
 230 .ti -8
 231 .BR "ip xfrm policy" " { " delete " | " get " }"
 232 .RI "{ " SELECTOR " | "
 233 .B index
 234 .IR INDEX " }"
 235 .B dir
 236 .I DIR
 237 .RB "[ " ctx
 238 .IR CTX " ]"
 239 .RB "[ " mark
 240 .I MARK
 241 .RB "[ " mask
 242 .IR MASK " ] ]"
 243 .RB "[ " ptype
 244 .IR PTYPE " ]"
 245
 246 .ti -8
 247 .BR "ip xfrm policy" " { " deleteall " | " list " }"
 248 .RI "[ " SELECTOR " ]"
 249 .RB "[ " dir
 250 .IR DIR " ]"
 251 .RB "[ " index
 252 .IR INDEX " ]"
 253 .RB "[ " ptype
 254 .IR PTYPE " ]"
 255 .RB "[ " action
 256 .IR ACTION " ]"
 257 .RB "[ " priority
 258 .IR PRIORITY " ]"
 259 .RB "[ " flag
 260 .IR FLAG-LIST "]"
 261
 262 .ti -8
 263 .B "ip xfrm policy flush"
 264 .RB "[ " ptype
 265 .IR PTYPE " ]"
 266
 267 .ti -8
 268 .B "ip xfrm policy count"
 269
 270 .ti -8
 271 .B "ip xfrm policy set"
 272 .RB "[ " hthresh4
 273 .IR LBITS " " RBITS " ]"
 274 .RB "[ " hthresh6
 275 .IR LBITS " " RBITS " ]"
 276
 277 .ti -8
 278 .IR SELECTOR " :="
 279 .RB "[ " src
 280 .IR ADDR "[/" PLEN "] ]"
 281 .RB "[ " dst
 282 .IR ADDR "[/" PLEN "] ]"
 283 .RB "[ " dev
 284 .IR DEV " ]"
 285 .RI "[ " UPSPEC " ]"
 286
 287 .ti -8
 288 .IR UPSPEC " := "
 289 .BR proto " {"
 290 .IR PROTO " |"
 291 .br
 292 .RB "{ " tcp " | " udp " | " sctp " | " dccp " } [ " sport
 293 .IR PORT " ]"
 294 .RB "[ " dport
 295 .IR PORT " ] |"
 296 .br
 297 .RB "{ " icmp " | " ipv6-icmp " | " mobility-header " } [ " type
 298 .IR NUMBER " ]"
 299 .RB "[ " code
 300 .IR NUMBER " ] |"
 301 .br
 302 .BR gre " [ " key
 303 .RI "{ " DOTTED-QUAD " | " NUMBER " } ] }"
 304
 305 .ti -8
 306 .IR DIR " := "
 307 .BR in " | " out " | " fwd
 308
 309 .ti -8
 310 .IR PTYPE " := "
 311 .BR main " | " sub
 312
 313 .ti -8
 314 .IR ACTION " := "
 315 .BR allow " | " block
 316
 317 .ti -8
 318 .IR FLAG-LIST " := [ " FLAG-LIST " ] " FLAG
 319
 320 .ti -8
 321 .IR FLAG " :="
 322 .BR localok " | " icmp
 323
 324 .ti -8
 325 .IR LIMIT-LIST " := [ " LIMIT-LIST " ]"
 326 .B limit
 327 .I LIMIT
 328
 329 .ti -8
 330 .IR LIMIT " :="
 331 .RB "{ " time-soft " | " time-hard " | " time-use-soft " | " time-use-hard " }"
 332 .IR "SECONDS" " |"
 333 .br
 334 .RB "{ " byte-soft " | " byte-hard " }"
 335 .IR SIZE " |"
 336 .br
 337 .RB "{ " packet-soft " | " packet-hard " }"
 338 .I COUNT
 339
 340 .ti -8
 341 .IR TMPL-LIST " := [ " TMPL-LIST " ]"
 342 .B tmpl
 343 .I TMPL
 344
 345 .ti -8
 346 .IR TMPL " := " ID
 347 .RB "[ " mode
 348 .IR MODE " ]"
 349 .RB "[ " reqid
 350 .IR REQID " ]"
 351 .RB "[ " level
 352 .IR LEVEL " ]"
 353
 354 .ti -8
 355 .IR ID " :="
 356 .RB "[ " src
 357 .IR ADDR " ]"
 358 .RB "[ " dst
 359 .IR ADDR " ]"
 360 .RB "[ " proto
 361 .IR XFRM-PROTO " ]"
 362 .RB "[ " spi
 363 .IR SPI " ]"
 364
 365 .ti -8
 366 .IR XFRM-PROTO " :="
 367 .BR esp " | " ah " | " comp " | " route2 " | " hao
 368
 369 .ti -8
 370 .IR MODE " := "
 371 .BR transport " | " tunnel " | " beet " | " ro " | " in_trigger
 372
 373 .ti -8
 374 .IR LEVEL " :="
 375 .BR required " | " use
 376
 377 .ti -8
 378 .BR "ip xfrm monitor" " ["
 379 .BI all-nsid
 380 ] [
 381 .BI all
 382  |
 383 .IR LISTofXFRM-OBJECTS " ]"
 384
 385 .ti -8
 386 .IR LISTofXFRM-OBJECTS " := [ " LISTofXFRM-OBJECTS " ] " XFRM-OBJECT
 387
 388 .ti -8
 389 .IR XFRM-OBJECT " := "
 390 .BR acquire " | " expire " | " SA " | " policy " | " aevent " | " report
 391
 392 .in -8
 393 .ad b
 394
 395 .SH DESCRIPTION
 396
 397 xfrm is an IP framework for transforming packets (such as encrypting
 398 their payloads). This framework is used to implement the IPsec protocol
 399 suite (with the
 400 .B state
 401 object operating on the Security Association Database, and the
 402 .B policy
 403 object operating on the Security Policy Database). It is also used for
 404 the IP Payload Compression Protocol and features of Mobile IPv6.
 405
 406 .TS
 407 l l.
 408 ip xfrm state add       add new state into xfrm
 409 ip xfrm state update    update existing state in xfrm
 410 ip xfrm state allocspi  allocate an SPI value
 411 ip xfrm state delete    delete existing state in xfrm
 412 ip xfrm state get       get existing state in xfrm
 413 ip xfrm state deleteall delete all existing state in xfrm
 414 ip xfrm state list      print out the list of existing state in xfrm
 415 ip xfrm state flush     flush all state in xfrm
 416 ip xfrm state count     count all existing state in xfrm
 417 .TE
 418
 419 .TP
 420 .IR ID
 421 is specified by a source address, destination address,
 422 .RI "transform protocol " XFRM-PROTO ","
 423 and/or Security Parameter Index
 424 .IR SPI "."
 425 (For IP Payload Compression, the Compression Parameter Index or CPI is used for
 426 .IR SPI ".)"
 427
 428 .TP
 429 .I XFRM-PROTO
 430 specifies a transform protocol:
 431 .RB "IPsec Encapsulating Security Payload (" esp "),"
 432 .RB "IPsec Authentication Header (" ah "),"
 433 .RB "IP Payload Compression (" comp "),"
 434 .RB "Mobile IPv6 Type 2 Routing Header (" route2 "), or"
 435 .RB "Mobile IPv6 Home Address Option (" hao ")."
 436
 437 .TP
 438 .I ALGO-LIST
 439 contains one or more algorithms to use. Each algorithm
 440 .I ALGO
 441 is specified by:
 442 .RS
 443 .IP \[bu]
 444 the algorithm type:
 445 .RB "encryption (" enc "),"
 446 .RB "authentication (" auth " or " auth-trunc "),"
 447 .RB "authenticated encryption with associated data (" aead "), or"
 448 .RB "compression (" comp ")"
 449 .IP \[bu]
 450 the algorithm name
 451 .IR ALGO-NAME
 452 (see below)
 453 .IP \[bu]
 454 .RB "(for all except " comp ")"
 455 the keying material
 456 .IR ALGO-KEYMAT ","
 457 which may include both a key and a salt or nonce value; refer to the
 458 corresponding RFC
 459 .IP \[bu]
 460 .RB "(for " auth-trunc " only)"
 461 the truncation length
 462 .I ALGO-TRUNC-LEN
 463 in bits
 464 .IP \[bu]
 465 .RB "(for " aead " only)"
 466 the Integrity Check Value length
 467 .I ALGO-ICV-LEN
 468 in bits
 469 .RE
 470
 471 .nh
 472 .RS
 473 Encryption algorithms include
 474 .BR ecb(cipher_null) ", " cbc(des) ", " cbc(des3_ede) ", " cbc(cast5) ","
 475 .BR cbc(blowfish) ", " cbc(aes) ", " cbc(serpent) ", " cbc(camellia) ","
 476 .BR cbc(twofish) ", and " rfc3686(ctr(aes)) "."
 477
 478 Authentication algorithms include
 479 .BR digest_null ", " hmac(md5) ", " hmac(sha1) ", " hmac(sha256) ","
 480 .BR hmac(sha384) ", " hmac(sha512) ", " hmac(rmd610) ", and " xcbc(aes) "."
 481
 482 Authenticated encryption with associated data (AEAD) algorithms include
 483 .BR rfc4106(gcm(aes)) ", " rfc4309(ccm(aes)) ", and " rfc4543(gcm(aes)) "."
 484
 485 Compression algorithms include
 486 .BR deflate ", " lzs ", and " lzjh "."
 487 .RE
 488 .hy
 489
 490 .TP
 491 .I MODE
 492 specifies a mode of operation for the transform protocol. IPsec and IP Payload
 493 Compression modes are
 494 .BR transport ", " tunnel ","
 495 and (for IPsec ESP only) Bound End-to-End Tunnel
 496 .RB "(" beet ")."
 497 Mobile IPv6 modes are route optimization
 498 .RB "(" ro ")"
 499 and inbound trigger
 500 .RB "(" in_trigger ")."
 501
 502 .TP
 503 .I FLAG-LIST
 504 contains one or more of the following optional flags:
 505 .BR noecn ", " decap-dscp ", " nopmtudisc ", " wildrecv ", " icmp ", "
 506 .BR af-unspec ", " align4 ", or " esn "."
 507
 508 .TP
 509 .IR SELECTOR
 510 selects the traffic that will be controlled by the policy, based on the source
 511 address, the destination address, the network device, and/or
 512 .IR UPSPEC "."
 513
 514 .TP
 515 .IR UPSPEC
 516 selects traffic by protocol. For the
 517 .BR tcp ", " udp ", " sctp ", or " dccp
 518 protocols, the source and destination port can optionally be specified.
 519 For the
 520 .BR icmp ", " ipv6-icmp ", or " mobility-header
 521 protocols, the type and code numbers can optionally be specified.
 522 For the
 523 .B gre
 524 protocol, the key can optionally be specified as a dotted-quad or number.
 525 Other protocols can be selected by name or number
 526 .IR PROTO "."
 527
 528 .TP
 529 .I LIMIT-LIST
 530 sets limits in seconds, bytes, or numbers of packets.
 531
 532 .TP
 533 .I ENCAP
 534 encapsulates packets with protocol
 535 .BR espinudp " or " espinudp-nonike ","
 536 .RI "using source port " SPORT ", destination port "  DPORT
 537 .RI ", and original address " OADDR "."
 538
 539 .sp
 540 .PP
 541 .TS
 542 l l.
 543 ip xfrm policy add      add a new policy
 544 ip xfrm policy update   update an existing policy
 545 ip xfrm policy delete   delete an existing policy
 546 ip xfrm policy get      get an existing policy
 547 ip xfrm policy deleteall        delete all existing xfrm policies
 548 ip xfrm policy list     print out the list of xfrm policies
 549 ip xfrm policy flush    flush policies
 550 .TE
 551
 552 .TP
 553 .IR SELECTOR
 554 selects the traffic that will be controlled by the policy, based on the source
 555 address, the destination address, the network device, and/or
 556 .IR UPSPEC "."
 557
 558 .TP
 559 .IR UPSPEC
 560 selects traffic by protocol. For the
 561 .BR tcp ", " udp ", " sctp ", or " dccp
 562 protocols, the source and destination port can optionally be specified.
 563 For the
 564 .BR icmp ", " ipv6-icmp ", or " mobility-header
 565 protocols, the type and code numbers can optionally be specified.
 566 For the
 567 .B gre
 568 protocol, the key can optionally be specified as a dotted-quad or number.
 569 Other protocols can be selected by name or number
 570 .IR PROTO "."
 571
 572 .TP
 573 .I DIR
 574 selects the policy direction as
 575 .BR in ", " out ", or " fwd "."
 576
 577 .TP
 578 .I CTX
 579 sets the security context.
 580
 581 .TP
 582 .I PTYPE
 583 can be
 584 .BR main " (default) or " sub "."
 585
 586 .TP
 587 .I ACTION
 588 can be
 589 .BR allow " (default) or " block "."
 590
 591 .TP
 592 .I PRIORITY
 593 is a number that defaults to zero.
 594
 595 .TP
 596 .I FLAG-LIST
 597 contains one or both of the following optional flags:
 598 .BR local " or " icmp "."
 599
 600 .TP
 601 .I LIMIT-LIST
 602 sets limits in seconds, bytes, or numbers of packets.
 603
 604 .TP
 605 .I TMPL-LIST
 606 is a template list specified using
 607 .IR ID ", " MODE ", " REQID ", and/or " LEVEL ". "
 608
 609 .TP
 610 .IR ID
 611 is specified by a source address, destination address,
 612 .RI "transform protocol " XFRM-PROTO ","
 613 and/or Security Parameter Index
 614 .IR SPI "."
 615 (For IP Payload Compression, the Compression Parameter Index or CPI is used for
 616 .IR SPI ".)"
 617
 618 .TP
 619 .I XFRM-PROTO
 620 specifies a transform protocol:
 621 .RB "IPsec Encapsulating Security Payload (" esp "),"
 622 .RB "IPsec Authentication Header (" ah "),"
 623 .RB "IP Payload Compression (" comp "),"
 624 .RB "Mobile IPv6 Type 2 Routing Header (" route2 "), or"
 625 .RB "Mobile IPv6 Home Address Option (" hao ")."
 626
 627 .TP
 628 .I MODE
 629 specifies a mode of operation for the transform protocol. IPsec and IP Payload
 630 Compression modes are
 631 .BR transport ", " tunnel ","
 632 and (for IPsec ESP only) Bound End-to-End Tunnel
 633 .RB "(" beet ")."
 634 Mobile IPv6 modes are route optimization
 635 .RB "(" ro ")"
 636 and inbound trigger
 637 .RB "(" in_trigger ")."
 638
 639 .TP
 640 .I LEVEL
 641 can be
 642 .BR required " (default) or " use "."
 643
 644 .sp
 645 .PP
 646 .TS
 647 l l.
 648 ip xfrm policy count    count existing policies
 649 .TE
 650
 651 .PP
 652 Use one or more -s options to display more details, including policy hash table
 653 information.
 654
 655 .sp
 656 .PP
 657 .TS
 658 l l.
 659 ip xfrm policy set      configure the policy hash table
 660 .TE
 661
 662 .PP
 663 Security policies whose address prefix lengths are greater than or equal
 664 policy hash table thresholds are hashed. Others are stored in the
 665 policy_inexact chained list.
 666
 667 .TP
 668 .I LBITS
 669 specifies the minimum local address prefix length of policies that are
 670 stored in the Security Policy Database hash table.
 671
 672 .TP
 673 .I RBITS
 674 specifies the minimum remote address prefix length of policies that are
 675 stored in the Security Policy Database hash table.
 676
 677 .sp
 678 .PP
 679 .TS
 680 l l.
 681 ip xfrm monitor         state monitoring for xfrm objects
 682 .TE
 683
 684 .PP
 685 The xfrm objects to monitor can be optionally specified.
 686
 687 .P
 688 If the
 689 .BI all-nsid
 690 option is set, the program listens to all network namespaces that have a
 691 nsid assigned into the network namespace were the program is running.
 692 A prefix is displayed to show the network namespace where the message
 693 originates. Example:
 694 .sp
 695 .in +2
 696 [nsid 1]Flushed state proto 0
 697 .in -2
 698 .sp
 699
 700 .SH AUTHOR
 701 Manpage revised by David Ward <david.ward@ll.mit.edu>
 702 .br
 703 Manpage revised by Christophe Gouault <christophe.gouault@6wind.com>
 704 .br
 705 Manpage revised by Nicolas Dichtel <nicolas.dichtel@6wind.com>