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