OVS-PKI(8)

📦
version 4.0.0 · 18 versions
, in ubuntu stonking

💖 ovs-pki — the OpenFlow public key infrastructure management utility, bestie edition 💖

okay so. you know how OpenFlow switches and controllers need to ~trust~ each other? yeah. that's the whole thing. this is the tool for it. it's ovs-pki, it lives in Open vSwitch, and it's genuinely not that scary once someone explains it to you like a person. sit down, grab a strawberry 🍓, let's go.

✨ SYNOPSIS ✨

every command you run looks like this:

ovs-pki <options> <command> <args>...

and here's the full roster of commands + their args, no gatekeeping:

  • ovs-pki init
  • ovs-pki req <name>
  • ovs-pki sign <name> [<type>]
  • ovs-pki req+sign <name> [<type>]
  • ovs-pki verify <name> [<type>]
  • ovs-pki fingerprint <file>
  • ovs-pki self-sign <name>

so, that <type> thing? it's a certificate type. your two options are switch (which is the default, bestie) or controller. that's it. that's the whole list. 💅

and the options you've got available:

  • -k <type> or --key=<type>
  • -B <nbits> or --bits=<nbits>
  • -D <file> or --dsaparam=<file>
  • -b or --batch
  • -f or --force
  • -d <dir> or --dir=<dir>
  • -l <file> or --log=<file>
  • -u or --unique
  • -h or --help

🌸 DESCRIPTION 🌸

the ovs-pki program sets up and manages a public key infrastructure for use with OpenFlow. the whole point is that it's a simple interface for organizations that don't already have a public key infrastructure sitting around, which, honestly? relatable. and if your org does have one, no worries — other PKI tools can substitute for or supplement the use of ovs-pki. it's not a jealous tool. 🫶

under the hood, ovs-pki uses openssl(1) for certificate management and key generation. not me outsourcing the hard part, the ancient one handles the crypto, we handle the vibes.

🎀 OFFLINE COMMANDS 🎀

these next ones are the ones you run when you're doing manual PKI administration. lowkey important. highkey important, actually.

init 👑

initializes a brand new PKI — by default in /var/lib/openvswitch/pki, although this default may be changed at Open vSwitch build time — and populates it with a pair of certificate authorities for controllers and switches. two CAs, one for each side, iconic behavior.

ideally you run this on a high-security machine that is completely separate from any OpenFlow controller or switch. that machine is called the CA machine. the files it produces, pki/controllerca/cacert.pem and pki/switchca/cacert.pem, need to be copied over to the OpenFlow switches and controllers, respectively. and good news: their contents may safely be made public. no secrets in those ones, fr fr.

by default, ovs-pki generates 2048-bit RSA keys. you can override the key length with the -B or --bits option (peep below 👇). and if you want DSA instead of RSA, hit it with -k dsa or --key=dsa. ⚠️ but — if you pick DSA, the dsaparam.pem file generated in the new PKI hierarchy must be copied to any machine on which the req command (see below) will be executed. its contents may safely be made public too, so don't stress about that part.

other files generated by init? those can just stay on the CA machine. except — listen — the files pki/controllerca/private/cakey.pem and pki/switchca/private/cakey.pem have particularly sensitive contents that should not be exposed. 🔥🔒 like, do not. these are the private CA keys. guard them with your life.

req <name> 🦋

generates a new private key named <name>-privkey.pem plus the corresponding certificate request named <name>-req.pem. the private key can be intended for use by a switch or a controller — you decide.

ideally you run this command on the switch or controller that will actually use the private key to identify itself. then the file <name>-req.pem gets copied over to the CA machine so it can be signed with the sign command (below).

btw as its final step, this command outputs a fingerprint to stdout. write that fingerprint down ✍️ and take it with you to the CA machine before you continue on to the sign step. seriously. don't skip the note-taking. you'll need it to verify later.

when RSA keys are in use (which is the default), req is special — unlike literally the rest of the ovs-pki commands, it does not need access to a PKI hierarchy created by ovs-pki init. freedom. 🕊️ the -B or --bits option (see below) may be used to specify the number of bits in the generated RSA key.

when DSA keys are used (that's when you specified --key=dsa), req does need access to the dsaparam.pem file created as part of the PKI hierarchy — but not to other files in that tree. by default, ovs-pki looks for this file in the PKI directory as dsaparam.pem, but -D or --dsaparam (see below) may be used to specify an alternate location.

💀 <name>-privkey.pem has sensitive contents that should not be exposed. <name>-req.pem may be safely made public. that's the rule, periodt.

sign <name> [<type>] ✍️

signs the certificate request named <name>-req.pem that was produced in the previous step, producing a certificate named <name>-cert.pem. <type> — which is either switch (the default) or controller — indicates the use for which the key is being certified.

this command must be run on the CA machine. no exceptions, no vibes-based workarounds.

it will output a fingerprint to stdout and then request that you verify that it is the same fingerprint output by the req command. this is the whole point: it ensures the request being signed is the same one produced by req. (the -b or --batch option suppresses that verification step, if you're feeling bold and scripty.)

the file <name>-cert.pem will need to be copied back to the switch or controller for which it is intended. and its contents may safely be made public. 🌈

req+sign <name> [<type>] 🔥

combines the req and sign commands into a single step, outputting all the files produced by each one. efficiency queen.

the <name>-privkey.pem and <name>-cert.pem files must be copied securely to the switch or controller. <name>-privkey.pem has sensitive contents and must not be exposed in transit — that's a hard no. and afterward, it should be deleted from the CA machine. clean up after yourself, bestie. 🧹

⚠️ so, this combined method is, theoretically, less secure than the individual steps performed separately on two different machines, because there's additional potential for exposure of the private key. however — and this is real — it's also more convenient. you gotta weigh that yourself. the manpage is just telling you the truth.

verify <name> [<type>] ✅

verifies that <name>-cert.pem is a valid certificate for the given <type> of use — either switch (the default) or controller. if the certificate is valid for this use, it prints the message <name>-cert.pem: OK; otherwise, it prints an error message. so if you see OK, you ate. if you don't… you didn't. 😭

fingerprint <file> 🔎

prints the fingerprint for <file>. now here's the nuance: if <file> is a certificate, then this is the SHA-1 digest of the DER encoded version of the certificate; otherwise, it is the SHA-1 digest of the entire file. different inputs, different math, same command. iykyk. 💅

self-sign <name> 🪞

signs the certificate request named <name>-req.pem using the private key <name>-privkey.pem, producing a self-signed certificate named <name>-cert.pem. the input files should have been produced with ovs-pki req.

and fun fact: some controllers accept such self-signed certificates. some. not all. know your audience. ✨

💅 OPTIONS 💅

  • -k <type>, --key=<type> — for the init command, this sets the public key algorithm to use for the new PKI hierarchy. for the req and req+sign commands, it sets the public key algorithm to use for the key to be generated — and it must match the value specified on init, so don't get cute and switch it up mid-project. with other commands, the value has no effect. the <type> may be rsa (the default) or dsa.
  • -B <nbits>, --bits=<nbits> — sets the number of bits in the key to be generated. when RSA keys are in use, this option affects only the init, req, and req+sign commands, and the same value should be given each time. when DSA keys are in use, this option affects only the init command. the value must be at least 1024. the default is 2048.
  • -D <file>, --dsaparam=<file> — specifies an alternate location for the dsaparam.pem file required by the req and req+sign commands. this option affects only those commands, and only when DSA keys are used. the default is dsaparam.pem under the PKI hierarchy.
  • -b, --batch — suppresses the interactive verification of fingerprints that the sign command by default requires. hands off the wheel, basically. 🚗💨
  • -d <dir>, --dir=<dir> — specifies the location of the PKI hierarchy to be used or created by the command. all commands, except req, need access to a PKI hierarchy. the default PKI hierarchy is /var/lib/openvswitch/pki, although this default may be changed at Open vSwitch build time.
  • -f, --force — by default, ovs-pki will not overwrite existing files or directories. this option overrides this behavior. ⚠️ use with intention, bestie, it's literally called force.
  • -l <file>, --log=<file> — sets the log file to <file>. the default is ovs-pki.log in the OVS log directory. the default OVS log directory is /var/log/openvswitch, although this default may be changed at Open vSwitch build time.
  • -u, --unique — changes the format of the certificate's Common Name (CN) field. by default, this field has the format <name> id:<uuid-or-date>. this option causes the provided name to be treated as unique and changes the format of the CN field to be simply <name>. cute and minimal. 🎀
  • -h, --help — prints a help usage message and exits. the classic. the icon. always there for you when you forget everything. 👑

👑 Author 👑

The Open vSwitch Development Community. absolute legends, all of them. 🫶

2016-2024, The Open vSwitch Development Community. respect the copyright, bestie, it's the law. 💜

and that's the whole page, you're done, you're certified, go forth and PKI responsibly. 🌟 this was Open vSwitch version 4.0, dated Aug 18, 2026, from manual page OVS-PKI(8). slay. 💖✨

📦 where this page comes from