xenserver: Set internal network-uuids in Bridge table on XS5.5

On XenServer 5.5, interface-reconfigure is not called when creating
internal bridges, so we jump through extra hoops to determine the
network UUIDs.  The code that handled this was not properly retrieving
the UUIDs from XAPI, so the field would never be set.  This commit
corrects that.

Bug #2666

ovs-ofctl: Document that "actions" must be last in flow specifications.

Bug #2447.
Reported-by: Reid Price <reid@nicira.com>

gre: Fix ICMP translation for path MTU discovery.

The translation of fragmentation-needed messages from outside the
tunnel to inside didn't quite make the transition from the old
GRE implementation to the new one intact.  This fixes a number of
minor bugs in the implmentation.  The primary issues are with computing
the tunnel header length and comparing the input vs. output values
for tunnel parameters such as the key.

stream: Fix typo in comment.

in-band: Refresh both local and remote rules even if local rules change.

This code should call refresh_remotes() even if refresh_local() returns
true.  That is, the normal C short-circuit evaluation of || is not desired
here.  So always call both.

in-band: Really reinstall in-band rules in in_band_flushed().

in-band: Remove comment that only a single controller is supported.

ovs-openflowd: Prefer --fail=standalone|secure over --fail=open|closed.

The "standalone" and "secure" terminology is less confusing.

This retains support for "open" and "closed" but does not document it.

ofproto: Add support for master/slave controller coordination.

Now that Open vSwitch has support for multiple simultaneous controllers,
there is some need for a degree of coordination among them.  For now, the
plan is for the controllers themselves to take the lead on this.  This
commit adds a small bit of OVS infrastructure: the ability for a controller
to designate itself as a "master" or a "slave".  There may be at most one
master at a time; when a controller designates itself as the master, then
any existing master is demoted to slave status.  Slave controllers are not
allowed to modify the flow table or global configuration; any attempt to
do so is rejected with a "bad request" error.

Feature #2495.

Add support for multiple OpenFlow controllers on a single bridge.

With this commit, Open vSwitch permits a bridge to have any number of
OpenFlow controllers.  When multiple controllers are configured, Open
vSwitch connects to all of them simultaneously.  Details of configuration
are in the vswitch schema documentation.

OpenFlow 1.0 does not specify how multiple controllers coordinate in
interacting with a single switch, so more than one controller should be
specified only if the controllers are themselves designed to coordinate
with each other.

An upcoming commit will provide a simple means for coordination between
multiple controllers.

Feature #2495.

ofproto: Bundle all controller-related settings into a struct.

Many ofproto settings are controller-related.  Upcoming commits will add
to ofproto the ability to support multiple controllers, so it is important
to be able to refer to controller settings as a group.  Hence, this commit
bundles them into a new "struct ofproto_controller".

in-band: Support an arbitrary number of controllers.

in-band: Drop in-band flows when turning off in-band control.

Destroying the in-band control object didn't remove the flows related to
in-band control, so they could persist until another event caused the
flow table to be reset.  Changing or removing the controller is one such
event, which would probably happen at the same time as turning off in-band
control, so this is a rather minor flaw, but it still seems good to fix it.

in-band: Fix memory leak in in_band_destroy().

in-band: Fix null pointer dereference.

Triggering this would require deleting the in-use datapath at just the
right time, but we still don't want it to happen.

in-band: Fix memory leak in get_remote_mac().

If the call to netdev_open_default() failed then next_hop_dev was not
freed, but it should be.

in-band: Fix inconsistency in in-band code.

The IBR_TO_LOCAL_ARP and IBR_FROM_LOCAL_ARP flows are dropped if there is
no local MAC.  I don't see why IBR_FROM_LOCAL_DHCP should be different, so
this commit adds it too.

ofproto: Make valgrind happy.

The "flags" member of struct odp_flow is not used for adding or deleting
flows, but valgrind doesn't know that.  By zeroing it out we can suppress
spurious warnings.

fail-open: Fix typo in comment.

ovs-openflowd: Remove documentation for obsolete --mgmt-id option.

Also remove unused OPT_MGMT_ID enum.

ovsdb-doc: Distinguish hyphens and minus signs in nroff output.

In nroff, a minus sign (\-) should generally be used in literal text,
whereas hyphens are generally correct elsewhere.  This roughly corresponds
to bold versus non-bold text, so this commit makes ovsdb-doc output "-"
that appears in input as a minus sign if it is bold or a hyphen if it is
not.

CodingStyle: Drop advice about breaking lines before binary operators.

I like the style that was prescribed here--I find it slightly easier to
read--but everyone else who submits code seems to prefer breaking
lines after binary operators instead.  No point in fighting the tide.

Document GRE port options.

xenserver: Restore original InterfaceReconfigure*.py on uninstall.

The %post script fragment in the RPM spec was moving aside the original
InterfaceReconfigure{,Bridge,Vswitch}.py scripts, but the %postun was
not restoring them.  This commit restores them in %postun.

Without this change, installing the openvswitch RPM on a stock XenServer
and then uninstalling it breaks XenServer networking.

Bug #2624.
Reported-by: Ram Jothikumar <rjothikumar@nicira.com>
Signed-off-by: Ben Pfaff <blp@nicira.com>

Fix broken build by adding forgotten header file to list of headers.

Update fake bond devices' statistics with the sum of bond slaves' stats.

Needed by XAPI to accurately report bond statistics.

Ugh.

Bug NIC-63.

tunneling: Remove old GRE implementation.

The new GRE implementation provides a complete drop in replacement
for the old Linux based implementation.  Therefore, remove the
old implementation and rename "grenew" to "gre".

tunneling: Add userspace support for new GRE implementation.

Add a netdev that supports the new datapath GRE implementation.
It currently coexists with the old implementation so it is named
"grenew".

netdev: Allow get_ifindex and get_features to be null.

Allow netdev providers to set get_ifindex and get_features it
null if they would always return EOPNOTSUPP.  This is particuarly
useful for virtual devices.

netdev-linux: Don't free a member of a struct.

We allocate struct netdev_linux which contains struct netdev but
free the netdev.  In practice this makes no difference because the
netdev is the first member of the struct but we should be correct
anyways.

netdev-linux: Check notifications are for netdev-linux device.

When receiving a change notification from rtnetlink we checked whether
a netdev of that name existed and if so tried to handle it.  This also
checks that the type of the device is one handled by netdev-linux.

tunneling: Add datapath GRE support.

Add a new vport type that implements GRE support inside of the
datapath instead of relying on Linux devices.  This provides
greater scalability, performance, and control.

The new GRE implementation supports nearly all features of the
Linux implementation.  It does not currently support multicast,
NBMA tunnels, or non-Ethernet devices.

This implementation of GRE has several important benefits over the
existing Linux implementation.  The first is simply that is not a
Linux device.  Linux devices are fairly heavy weight both in terms
of memory consumption and interactions with the rest of the system
(notifications, processes polling, etc.).  There are many pieces of
code that make assumptions about the maximum reasonable number of
ports.  Simply maintaining the state of several thousand devices is
enough to full occupy the CPU.

A tighter coupling between the GRE implementation and datapath
also allows more flexibility.  The key can be set and retrieved
from the flow table, which allows even greater scalability.
There will probably be additional use cases in the future.

datapath: Add function to copy skb checksum bits.

Some kernels don't copy the checksum offload state in the skb
header when doing different types of copies.  Xen adds even more
fields, which are also not consistently copied.  The result is
uninitialized memory and random outcomes.  This adds a function to
consistently copy these bits across all kernel versions.

datapath: Add skb_csum_help compatibility function.

Later kernel versions remove the direction argument from
skb_checksum_help.  This provides a compatibility function so we
can have consistent syntax across versions.

Since CHECKSUM_PARTIAL is the same as CHECKSUM_HW on older kernels
this allows a unified code path for computing checksums.

datapath: Genericize hash table.

Currently the flow hash table assumes that it is storing flows.
However, we will need additional types of hash tables in the
future so remove assumptions about flows and convert the datapath
to use the new table.

dpif-linux: Clean up vports that are no longer in config.

If the config changes while ovs-vswitchd is not running it is possible
that there could be some vports which are no longer needed but won't
be destroyed when closed because they aren't open.  This deletes
unneeded vports at the same time that we clean up unneeded datapaths.

netdev: Add function netdev_is_open().

Add netdev_is_open(), which checks to see if a given netdev is
currently open.  It will be used to assist in cleaning up old ports
that are no longer in use.

datapath: Add generic virtual port layer.

Currently the datapath directly accesses devices through their
Linux functions.  Obviously this doesn't work for virtual devices
that are not backed by an actual Linux device.  This creates a
new virtual port layer which handles all interaction with devices.

The existing support for Linux devices was then implemented on top
of this layer as two device types.  It splits out and renames dp_dev
to internal_dev.  There were several places where datapath devices
had to handled in a special manner and this cleans that up by putting
all the special casing in a single location.

datapath: Don't read net namespace on kernels that don't use them.

Use macros to eliminate the network namespace argument before it
gets to the compiler.  This allows us to specify a namespace on
kernels that know about them and prevent the compiler from complaining
on kernels that don't.

datapath: Add rtnl_is_locked compatibility function.

rtnl_is_locked wasn't added until 2.6.26 so provide an implementation
of it.

datapath: Add dev_get_stats compatibility function.

The dev_get_stats function wasn't added until 2.6.29 so provide
a replacement for it.

tunneling: Add support for tunnel ID.

Add a tun_id field which contains the ID of the encapsulating tunnel
on which a packet was received (0 if not received on a tunnel).  Also
add an action which allows the tunnel ID to be set for outgoing
packets.  At this point there aren't any tunnel implementations so
these fields don't have any effect.

The matching is exposed to OpenFlow by overloading the high 32 bits
of the cookie as the tunnel ID.  ovs-ofctl is capable of turning
on this special behavior using a new "tun-cookie" command but this
command is intentially undocumented to avoid it being used without
a full understanding of the consequences.

bridge: Don't learn from inadmissible flows when revising learning table.

Various kinds of flows are inadmissible and must be dropped.  Most notably,
OVS drops packets received on a bond whose destinations are ones that OVS
has already learned on a different port.  As the comment says:

         /* Drop all packets for which we have learned a different input
          * port, because we probably sent the packet on one slave and got
          * it back on the other.  Broadcast ARP replies are an exception
          * to this rule: the host has moved to another switch. */

As an important side effect of dropping these packets, OVS does not use
them for MAC learning when it sets up the corresponding flows.

However, OVS also periodically scans the datapath flow table and uses
information about flow activity to update its learning tables.  (Otherwise,
learning table entries could expire because no new flows were being set up,
even though active flows existed.)  This process, implemented in
bridge_account_flow_ofhook_cb(), did not check for admissibility, so
packets received on a bond could be used for learning even though another
port had already been learned.

This commit fixes the problem by making bridge_account_flow_ofhook_cb()
check for admissibility.

QA notes: Reproducing this problem requires some care and some luck.  One
way is to have two VMs with network interfaces on a single bonded network.
Both bonded interfaces must be up (otherwise packets sent out on one slave
will never be received on the other).  The problem will also not occur if
the physical switch that the bond slaves are plugged into has learned the
MAC address of the VMs involved (because the physical switch will then,
again, drop the packets without sending them back in on the other slave).
Finally, there needs to be some luck in timing and perhaps with the OVS
internal hash function also.

(One way to reproduce it reliably is to plug a pair of Ethernet ports into
each other with a cable, without an intermediate switch, and then use that
pair of ports as a bond.  Then every packet sent out on one will
immediately be received on the other, triggering the problem fairly often.
If this doesn't work at first, try changing the Ethernet address used on
one side or the other.)

To verify that the problem being observed is the one fixed by this commit,
turn on bridge debugging with "ovs-appctl vlog/set bridge:file" and look
for "bridge xapi2: learned that 00:01:02:03:04:06 is on port bond0 in VLAN
0" where 00:01:02:03:04:06 is a VM's Ethernet address and bond0 is the
name of the bond in the ovs-vswitchd log file.

Testing: I ran the "loopback bond" test above with and without this commit,
twice each in case I was just lucky.

CC: Henrik Amren <henrik@nicira.com>
Bug #2366.
Bug NIC-64.
Bug NIC-69.

bridge: Factor admissibility check out of process_flow().

The next commit will need to make the same tests as the first part of
process_flow(), so this commit breaks that out into a new function
is_admissible().

Should have no externally visible effect.

bridge: Minor cleanup in process_flow().

Should have no externally visible effect.

bridge: Don't log warnings when revalidating.

The rest of the warnings along this path follow this rule, but this one
didn't.  Make it consistent.

xenserver: Fix name of veth module so it can be loaded on startup

netdev: Add support for "patch" type

This commit introduces a new netdev type called "patch".  A patch is a
pair of interfaces, in which frames sent through one of the devices
pop out of the other.  This is useful for linking together datapaths.

A patch's only argument on creation is "peer", which specifies the other
side of the patch.  A patch must be created in pairs, so a second netdev
must be created with the "name" and "peer" values reversed.

The current implementation is built using veth devices.  Further, it's
limited to the veth devices which support configuration through sysfs.
This limits the ability to use a "patch" on 2.6.18 kernels using the
veth device we include (read: flavors of XenServer 5.5).  In the not too
distant future, the implementation will be modified to use the new
kernel port abstraction introduced by Jesse Gross's forthcoming GRE
work.  At that point, patch devices will work on any Linux platform
supported by OVS.

xenserver: Load veth driver on 2.6.18 systems

In a future commit, the "patch" netdev type will be introduced.  The
initial implementation will be based on veth, for which we have a kernel
module on 2.6.18.  A more general solution will be used in the future,
at which time, this loading of the veth module can be removed.

veth: Fix problems removing veth devices

When a user tried to delete a veth device through sysfs, the driver
wasn't properly parsing the device name.  Also, it called
dev_get_by_name(), which increments a refcount on the device, but didn't
make a dev_put() before trying to delete it.

ovs-vsctl: Cleanup some formatting in man page

ofproto: Use original in_port for executing NXAST_RESUBMIT actions.

If NXAST_RESUBMIT adopts the replacement in_port for executing actions,
then OFPP_NORMAL will believe that traffic originated from whatever port
that is.  This seems unlikely to ever be useful and in fact breaks
applications that use NXAST_RESUBMIT for two-stage ACLs.

Bug #2644.

stream-ssl: Avoid access-after-free error in update_ssl_config().

Commit b84f503d "stream-ssl: Read existing CA certificate more eagerly
during bootstrap" inadvertently introduced an access-after-free error:

  do_ca_cert_bootstrap() calls
    stream_ssl_set_ca_cert_file(ca_cert.file_name, true), which calls
      update_ssl_config(&ca_cert, file_name), which calls
        free(ca_cert.file_name) then xstrdup(ca_cert.file_name).

Fix the problem.

Reported-by: Cedric Hobbs <cedric@nicira.com>
Reported-by: Peter Balland <peter@nicira.com>

ovs-ofctl: Fix write before beginning of string in "add-flow".

If "action" is the first word in a flow specification, then we were writing
one byte before the beginning of the string.  So overwrite the 'a' in
"action" instead; we know it's really there.

Reported-by: Ghanem Bahri <bahri.ghanem@gmail.com>

configure: Convert --with-l26=<dir> argument to absolute path.

If the argument to --with-l26 is given as a relative pathname, then if
configuration succeeds, the build will fail, because the current directory
during the kernel build is different from that at configuration time.
Avoid the problem by converting the argument to an absolute path if
necessary.

odp-util: Print bad action numbers in hexadecimal in format_odp_action().

Given that dpif.c clears action numbers to 0xcccc it can be much less
mystifying to see that instead of 52428.

dpif: Make dpif_flow_get() results predictable on error.

If dpif_flow_get()'s caller is less cautious than it should be, then it
will get surprising results when it looks at the returned flow on error.
This commit at least gives it plausible results.

ovs-dpctl: In "dump-flows", only print flows that can be retrieved.

If dpif_flow_get() returns an error then we'd better not try to print
the flow (especially not the actions since check_rw_odp_flow() clears
the first action to 0xcc).

ofproto: Maximum value of "int" is INT_MAX, not UINT32_MAX.

This bug seems to be dormant at the moment, since the -1 gets passed
through unchanged to do_send_packet_in() and then to make_packet_in()
and then gets converted to SIZE_MAX as part of the MIN invocation in that
function.  It is still better to fix it.

Reported-by: Jean Tourrilhes <jt@hpl.hp.com>

ofproto: Make NXAST_RESUBMIT take header modifications into account.

Until now, the NXAST_RESUBMIT action has always looked up the original
flow except for the updated in_port.  This commit changes the semantics to
instead look up the flow as modified by any preceding actions that affect
it, e.g. if OFPAT_SET_VLAN_VID precedes NXAST_RESUBMIT, then NXAST_RESUBMIT
now looks up the flow with the modified VLAN, not the original (as well as
the modified in_port).

Also, document how NXAST_RESUBMIT is supposed to work.

Suggested-by: Paul Ingram <paul@nicira.com>

ofproto: Copy the flow being translated in xlate_actions().

This change should have no user-visible effect, but it paves the way for
the following commit, which requires the action_xlate_ctx's flow to be
modifiable.

Make fatal signals cause an exit more promptly in special cases.

The fatal-signal library notices and records fatal signals (e.g. SIGTERM)
and terminates the process on the next trip through poll_block().  But
some special utilities do not always invoke poll_block() promptly, e.g.
"ovs-ofctl monitor" does not call poll_block() as long as OpenFlow messages
are available.  But these special cases seem like they are all likely to
call into functions that themselves block (those with "_block" in their
names).  So make a new rule that such functions should always call
fatal_signal_run(), either directly or through poll_block().  This commit
implements and documents that rule.

Bug #2625.

xenserver: Fix ip_gre_mod modprobe issue in init script

The OVS kernel modules were moved to kernel/extra/openvswitch, but the
init script wasn't updated to look for the ip_gre_mod kernel module
there.  This commit fixes that.

CC: Paul Ingram <paul@nicira.com>

xenserver: Allow use first class datamodel field for controller IP

Starting in XenServer 5.6.0, a "vswitch_controller" key is available to
store the controller's IP address in the "pool" table of XAPI.  Older
versions must still use the "vSwitchController" key in "other_config".

Based on commits 37fee7 and 0ebd737 from the xs5.7 branch written by
Ian Campbell.

xenserver: Only register xsconsole plugin if OVS is running

The 5.6.0 XenServer release will include OVS but not have it enabled by
default.  By only registering the xsconsole plugin on systems running OVS,
this plugin can be included in the main distribution.

Based on commit 0ebd737 from the xs5.7 branch written by Ian Campbell.

xenserver: Do not raise XenAPIPlugin.Failure in xsconsole plugin

Do not raise XenAPIPlugin.Failure, it is not an exception xsconsole will
handle.

Based on commit fcc495 from the xs5.7 branch written by Ian Campbell.

vswitch: Fix documentation for network-uuids external ID in Bridge table.

Jeremy pointed out that this field is semicolon-delimited but we document
it as space-delimited.  Fix the documentation.

Reported-by: Jeremy Stribling <strib@nicira.com>

ovsdb: Use port 6632 as a default port for database connections.

Until now we have required a port number to be specified explicitly for
database connections.  This commit adopts port 6632 as a default.

vconn-stream: Factor out port defaults into public helper functions.

These functions will be used elsewhere in an upcoming commit.

stream: Generalize stream_open_block().

This change makes it possible to separate opening a stream from blocking on
connection completion.  This avoids some code redundancy in an upcoming
commit.

ovs-controller: Document how to use with management protocol.

jsonrpc: Add support for passive connections.

This allows ovs-vsctl to work as a simple Open vSwitch "manager" if the
XenServer host is configured to connect to it remotely.

reconnect: Implement "passive mode".

This allows the reconnect library to support clients that want to listen
for an incoming connection.

reconnect: Get rid of unused state.

Nothing ever caused the reconnect FSM to transition to the S_START_CONNECT
state, so we might as well get rid of the code for it.

stream-ssl: Make it possible to avoid checking peer SSL certificate.

In Citrix XenServer, the hosts have SSL private keys and certificates, but
those certificates are not signed by any certificate authority.  So we
must provide a way to avoid checking certificates against a CA if we want
other OVS tools to be able to talk to XenServer hosts over SSL.  This
commit makes that possible.

stream: New functions stream_verify_name() and pstream_verify_name().

These functions can be useful for checking whether a given name is an
active or passive connection method.

The implementation is cut-and-paste from vconn_verify_name() and
pvconn_verify_name().

ovs-vsctl: Add SSL support.

Normally ovs-vsctl is run locally, with a Unix domain socket as target, but
it can be useful over SSL as well from a remote host, so this commit
enables that use.

ovs-controller: Add --unixctl option.

ovsdb-server: Document --unixctl option.

Fix hyphens in manpage.

stream-ssl: Read existing CA certificate more eagerly during bootstrap.

When do_ca_cert_bootstrap() attempts to bootstrap a CA certificate from a
remote host, it gives up if the CA certificate file already exists.  It
knows that this file did not exist some time earlier (because it checked),
so it logged a warning and just returns.  The next time that
stream_ssl_set_ca_cert_file() gets called, it will read the new CA
certificate file and all will be well.

That works OK in ovsdb-server, which calls stream_ssl_set_ca_cert_file()
every time through its main loop.  It does not work well for ovs-vswitchd,
which only calls that function when it needs to reconfigure.  But it
should work fine to call it directly from do_ca_cert_bootstrap(), so this
commit changes it to do that.

Bug #2635.

print: Print mod_vlan_vid action in decimal

In a flow description, the VLAN VID was printed in hex, but an VLAN VID
modification would print the value in decimal.  This commit consistently
prints the value in decimal.

CC: Paul Ingram <paul@nicira.com>

ovs-ofctl: Allow setting cookie as a decimal or hex value

Clean-up a few items related to flow cookies:

    - Allow setting the flow cookie as a hex or decimal string
    - Consistently print the cookie in hex
    - Document the ability to set the flow cookie in ovs-ofctl.

netdev: Allow recv, recv_wait, drain, send, send_wait to be null.

Suggested by partner.

vswitch: Mark bridge_update_desc argument as unused

The implementation of bridge_update_desc() is empty, which causes a
compiler warning for the argument.  Mark the argument unused until we
get a chance to fix the function's implementation.

leak-checker: Document "--leak-limit" option

xenserver: Put kernel modules in "extra" directory

This change cleans up a couple of items.  First, it makes sure that our
newly installed kernel modules are picked up instead of any ones that
shipped with XenServer.  Second, it prevents having to do the install
with "--nodeps".

interface-reconfigure+vif: accept openvswitch in /etc/xensource/network.conf

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

vswitchd: Fix small memory leak in bridge_init

xenserver: Remove stray "\" in spec file

dpif: Really don't log many dpif errors.

The comment here was out of touch with the actual definition.  Limiting a
log message to 9999 per minute is not much of a limit!

I suspect that I turned this way up during initial development at some
point and forgot to turn it down to a reasonable level.

xenserver: Don't install xsconsole plugin as symlink

The OVS xsconsole plugin used to be installed in
/usr/share/openvswitch/scripts directory and then a symlink was created
to the /usr/lib/xsconsole/plugins-base directory.  The Citrix packaging of
OVS just placed it directly into the xsconsole plugin directory.  This
worked fine until we renamed our package "openvswitch", which is the
same as Citrix uses.

On an upgrade, the default package handler would attempt to clean up files
that were in the Cirix packaging, but not in the upgraded package.  Since
it didn't know that we had replaced their plugin with our symlink, it would
destroy our symlink.

This commit just places the plugin directly into the
/usr/lib/xsconsole/plugins-base directory, which allows us to seamlessly
upgrade to newer Open vSwitch versions.

Bug #2608

xenserver: Minor spec file cleanups

Remove compiled InterfaceReconfigure byte code on uninstall.  Also, fix
minor typo in error message.

xenserver: Only rotate files that end in .log

vswitchd: Make the bond rebalancing interval user-configurable.

This may make some bond debugging problems easier.  It also seems
reasonable to expose this parameter to the user.

Related to bug #2366.

ovs-vsctl: Allow setting arbitrary database columns in add-port, add-bond.

ofproto: Make OFPFC_MODIFY and OFPFC_MODIFY_STRICT add a flow if no match.

OpenFlow 1.0 says that OFPFC_MODIFY and OFPFC_MODIFY_STRICT are supposed
to add the specified flow to the flow table if it does not already contain
one that matches.

Reported-by: Natasha Gude <natasha@nicira.com>
Bug #2506.

ovs-ofctl: Add support for "resubmit" Nicira vendor extension.

CC: Paul Ingram <paul@nicira.com>

debian: Updated templates.pot

The various fixes that were made earlier caused a new templates.pot file
to be generated.

debian: Cleanup config template for Lintian

Lintian wants "boolean" to be used instead of "select" if there are only
two choices.  It also wants short descriptions to not end in a period.