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" " [ " all " |"
 368 .IR LISTofXFRM-OBJECTS " ]"
 369
 370 .ti -8
 371 .IR LISTofXFRM-OBJECTS " := [ " LISTofXFRM-OBJECTS " ] " XFRM-OBJECT
 372
 373 .ti -8
 374 .IR XFRM-OBJECT " := "
 375 .BR acquire " | " expire " | " SA " | " policy " | " aevent " | " report
 376
 377 .in -8
 378 .ad b
 379
 380 .SH DESCRIPTION
 381
 382 xfrm is an IP framework for transforming packets (such as encrypting
 383 their payloads). This framework is used to implement the IPsec protocol
 384 suite (with the
 385 .B state
 386 object operating on the Security Association Database, and the
 387 .B policy
 388 object operating on the Security Policy Database). It is also used for
 389 the IP Payload Compression Protocol and features of Mobile IPv6.
 390
 391 .TS
 392 l l.
 393 ip xfrm state add       add new state into xfrm
 394 ip xfrm state update    update existing state in xfrm
 395 ip xfrm state allocspi  allocate an SPI value
 396 ip xfrm state delete    delete existing state in xfrm
 397 ip xfrm state get       get existing state in xfrm
 398 ip xfrm state deleteall delete all existing state in xfrm
 399 ip xfrm state list      print out the list of existing state in xfrm
 400 ip xfrm state flush     flush all state in xfrm
 401 ip xfrm state count     count all existing state in xfrm
 402 .TE
 403
 404 .TP
 405 .IR ID
 406 is specified by a source address, destination address,
 407 .RI "transform protocol " XFRM-PROTO ","
 408 and/or Security Parameter Index
 409 .IR SPI "."
 410 (For IP Payload Compression, the Compression Parameter Index or CPI is used for
 411 .IR SPI ".)"
 412
 413 .TP
 414 .I XFRM-PROTO
 415 specifies a transform protocol:
 416 .RB "IPsec Encapsulating Security Payload (" esp "),"
 417 .RB "IPsec Authentication Header (" ah "),"
 418 .RB "IP Payload Compression (" comp "),"
 419 .RB "Mobile IPv6 Type 2 Routing Header (" route2 "), or"
 420 .RB "Mobile IPv6 Home Address Option (" hao ")."
 421
 422 .TP
 423 .I ALGO-LIST
 424 contains one or more algorithms to use. Each algorithm
 425 .I ALGO
 426 is specified by:
 427 .RS
 428 .IP \[bu]
 429 the algorithm type:
 430 .RB "encryption (" enc "),"
 431 .RB "authentication (" auth " or " auth-trunc "),"
 432 .RB "authenticated encryption with associated data (" aead "), or"
 433 .RB "compression (" comp ")"
 434 .IP \[bu]
 435 the algorithm name
 436 .IR ALGO-NAME
 437 (see below)
 438 .IP \[bu]
 439 .RB "(for all except " comp ")"
 440 the keying material
 441 .IR ALGO-KEYMAT ","
 442 which may include both a key and a salt or nonce value; refer to the
 443 corresponding RFC
 444 .IP \[bu]
 445 .RB "(for " auth-trunc " only)"
 446 the truncation length
 447 .I ALGO-TRUNC-LEN
 448 in bits
 449 .IP \[bu]
 450 .RB "(for " aead " only)"
 451 the Integrity Check Value length
 452 .I ALGO-ICV-LEN
 453 in bits
 454 .RE
 455
 456 .nh
 457 .RS
 458 Encryption algorithms include
 459 .BR ecb(cipher_null) ", " cbc(des) ", " cbc(des3_ede) ", " cbc(cast5) ","
 460 .BR cbc(blowfish) ", " cbc(aes) ", " cbc(serpent) ", " cbc(camellia) ","
 461 .BR cbc(twofish) ", and " rfc3686(ctr(aes)) "."
 462
 463 Authentication algorithms include
 464 .BR digest_null ", " hmac(md5) ", " hmac(sha1) ", " hmac(sha256) ","
 465 .BR hmac(sha384) ", " hmac(sha512) ", " hmac(rmd610) ", and " xcbc(aes) "."
 466
 467 Authenticated encryption with associated data (AEAD) algorithms include
 468 .BR rfc4106(gcm(aes)) ", " rfc4309(ccm(aes)) ", and " rfc4543(gcm(aes)) "."
 469
 470 Compression algorithms include
 471 .BR deflate ", " lzs ", and " lzjh "."
 472 .RE
 473 .hy
 474
 475 .TP
 476 .I MODE
 477 specifies a mode of operation for the transform protocol. IPsec and IP Payload
 478 Compression modes are
 479 .BR transport ", " tunnel ","
 480 and (for IPsec ESP only) Bound End-to-End Tunnel
 481 .RB "(" beet ")."
 482 Mobile IPv6 modes are route optimization
 483 .RB "(" ro ")"
 484 and inbound trigger
 485 .RB "(" in_trigger ")."
 486
 487 .TP
 488 .I FLAG-LIST
 489 contains one or more of the following optional flags:
 490 .BR noecn ", " decap-dscp ", " nopmtudisc ", " wildrecv ", " icmp ", "
 491 .BR af-unspec ", " align4 ", or " esn "."
 492
 493 .TP
 494 .IR SELECTOR
 495 selects the traffic that will be controlled by the policy, based on the source
 496 address, the destination address, the network device, and/or
 497 .IR UPSPEC "."
 498
 499 .TP
 500 .IR UPSPEC
 501 selects traffic by protocol. For the
 502 .BR tcp ", " udp ", " sctp ", or " dccp
 503 protocols, the source and destination port can optionally be specified.
 504 For the
 505 .BR icmp ", " ipv6-icmp ", or " mobility-header
 506 protocols, the type and code numbers can optionally be specified.
 507 For the
 508 .B gre
 509 protocol, the key can optionally be specified as a dotted-quad or number.
 510 Other protocols can be selected by name or number
 511 .IR PROTO "."
 512
 513 .TP
 514 .I LIMIT-LIST
 515 sets limits in seconds, bytes, or numbers of packets.
 516
 517 .TP
 518 .I ENCAP
 519 encapsulates packets with protocol
 520 .BR espinudp " or " espinudp-nonike ","
 521 .RI "using source port " SPORT ", destination port "  DPORT
 522 .RI ", and original address " OADDR "."
 523
 524 .sp
 525 .PP
 526 .TS
 527 l l.
 528 ip xfrm policy add      add a new policy
 529 ip xfrm policy update   update an existing policy
 530 ip xfrm policy delete   delete an existing policy
 531 ip xfrm policy get      get an existing policy
 532 ip xfrm policy deleteall        delete all existing xfrm policies
 533 ip xfrm policy list     print out the list of xfrm policies
 534 ip xfrm policy flush    flush policies
 535 .TE
 536
 537 .TP
 538 .IR SELECTOR
 539 selects the traffic that will be controlled by the policy, based on the source
 540 address, the destination address, the network device, and/or
 541 .IR UPSPEC "."
 542
 543 .TP
 544 .IR UPSPEC
 545 selects traffic by protocol. For the
 546 .BR tcp ", " udp ", " sctp ", or " dccp
 547 protocols, the source and destination port can optionally be specified.
 548 For the
 549 .BR icmp ", " ipv6-icmp ", or " mobility-header
 550 protocols, the type and code numbers can optionally be specified.
 551 For the
 552 .B gre
 553 protocol, the key can optionally be specified as a dotted-quad or number.
 554 Other protocols can be selected by name or number
 555 .IR PROTO "."
 556
 557 .TP
 558 .I DIR
 559 selects the policy direction as
 560 .BR in ", " out ", or " fwd "."
 561
 562 .TP
 563 .I CTX
 564 sets the security context.
 565
 566 .TP
 567 .I PTYPE
 568 can be
 569 .BR main " (default) or " sub "."
 570
 571 .TP
 572 .I ACTION
 573 can be
 574 .BR allow " (default) or " block "."
 575
 576 .TP
 577 .I PRIORITY
 578 is a number that defaults to zero.
 579
 580 .TP
 581 .I FLAG-LIST
 582 contains one or both of the following optional flags:
 583 .BR local " or " icmp "."
 584
 585 .TP
 586 .I LIMIT-LIST
 587 sets limits in seconds, bytes, or numbers of packets.
 588
 589 .TP
 590 .I TMPL-LIST
 591 is a template list specified using
 592 .IR ID ", " MODE ", " REQID ", and/or " LEVEL ". "
 593
 594 .TP
 595 .IR ID
 596 is specified by a source address, destination address,
 597 .RI "transform protocol " XFRM-PROTO ","
 598 and/or Security Parameter Index
 599 .IR SPI "."
 600 (For IP Payload Compression, the Compression Parameter Index or CPI is used for
 601 .IR SPI ".)"
 602
 603 .TP
 604 .I XFRM-PROTO
 605 specifies a transform protocol:
 606 .RB "IPsec Encapsulating Security Payload (" esp "),"
 607 .RB "IPsec Authentication Header (" ah "),"
 608 .RB "IP Payload Compression (" comp "),"
 609 .RB "Mobile IPv6 Type 2 Routing Header (" route2 "), or"
 610 .RB "Mobile IPv6 Home Address Option (" hao ")."
 611
 612 .TP
 613 .I MODE
 614 specifies a mode of operation for the transform protocol. IPsec and IP Payload
 615 Compression modes are
 616 .BR transport ", " tunnel ","
 617 and (for IPsec ESP only) Bound End-to-End Tunnel
 618 .RB "(" beet ")."
 619 Mobile IPv6 modes are route optimization
 620 .RB "(" ro ")"
 621 and inbound trigger
 622 .RB "(" in_trigger ")."
 623
 624 .TP
 625 .I LEVEL
 626 can be
 627 .BR required " (default) or " use "."
 628
 629 .sp
 630 .PP
 631 .TS
 632 l l.
 633 ip xfrm policy count    count existing policies
 634 .TE
 635
 636 .PP
 637 Use one or more -s options to display more details, including policy hash table
 638 information.
 639
 640 .sp
 641 .PP
 642 .TS
 643 l l.
 644 ip xfrm policy set      configure the policy hash table
 645 .TE
 646
 647 .PP
 648 Security policies whose address prefix lengths are greater than or equal
 649 policy hash table thresholds are hashed. Others are stored in the
 650 policy_inexact chained list.
 651
 652 .TP
 653 .I LBITS
 654 specifies the minimum local address prefix length of policies that are
 655 stored in the Security Policy Database hash table.
 656
 657 .TP
 658 .I RBITS
 659 specifies the minimum remote address prefix length of policies that are
 660 stored in the Security Policy Database hash table.
 661
 662 .sp
 663 .PP
 664 .TS
 665 l l.
 666 ip xfrm monitor         state monitoring for xfrm objects
 667 .TE
 668
 669 .PP
 670 The xfrm objects to monitor can be optionally specified.
 671
 672 .SH AUTHOR
 673 Manpage revised by David Ward <david.ward@ll.mit.edu>
 674 .br
 675 Manpage revised by Christophe Gouault <christophe.gouault@6wind.com>