.. _cloud-up-licenses:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Licenses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Licenses in RLM Cloud are always created against a specific license server, from a
product definition or product bundle that you created earlier (see :ref:`cloud-up-products`). This
section describes how to add, replace, and delete licenses, how the portal writes those changes to
the server, and how to manage meters and live checkouts.

------

.. _cloud-up-add-license:

############################
Adding a License to a Server
############################

Licenses are created from the server's **Configuration** page. Open the server you want to license
and press **Add License** (requires **Edit**). The license form opens.

* **Product** – choose the product definition for the license. To license a bundle instead, turn on
  **Use Bundle** and choose a bundle; the portal then creates one license per product in the bundle.
* **License Count** – the number of licenses to create. This field appears only for floating
  (counted) products and must be 1 or greater. For nodelocked, token, and metered products the count
  is fixed at 1 and the field is not shown.
* **Override product definition defaults** – when this is off, the license inherits its expiration
  and version from the product definition. When it is on, you can set:

	* **Expiration** – Permanent, a number of days, or a fixed date.
	* **Version** – Normal (*n.n*) or a date-based number of months.

* **Notes** – optional free-form notes.
* **Options** – optional additional RLM keyword/value pairs.

Press **Create License** to create the license.

------

.. _cloud-up-replace-delete:

################################
Replacing and Deleting a License
################################

Both operations are performed from the license table on the server's Configuration page and require
**Edit**.

* **Replace** – replace an existing license with a new one. In replace mode the product (or bundle)
  is locked and cannot be changed; you adjust the remaining license settings and create the
  replacement.
* **Delete** – remove the license. Deleting a license removes the license file from the server and
  triggers a reread so that the change takes effect.

------

.. _cloud-up-license-writes:

############################
How License Writes Work
############################

Creating, replacing, and deleting a license writes to the license server as a background job. The
page polls for the result and shows a success or error toast when the job finishes; this may take a
few seconds.

.. note:: If a server is missing the connection data needed to reach it, the license record is still
	created in the portal database, but nothing is written to the server itself. Once the server's
	connection data is in place, you can write the license to the server.

------

.. _cloud-up-edit-meter:

############################
Editing a Meter
############################

For metered products you can add count to a license's meter directly from the portal (requires
**Manage**).

On the **Cloud Servers** page, expand a server and then expand the metered product pool, and click
the **Edit Meter** (gauge) icon. The Edit Meter dialog shows the **Counter** name and the current
**Count**.

.. TODO: screenshot

Enter a whole number in **Count to Add** (from 1 up to 2,147,483,647) and press **Update** to
increment the meter. The change is recorded in the **Audit Log**.

------

.. _cloud-up-checkouts:

##############################
Viewing and Removing Checkouts
##############################

Expand a server's product pool to see the licenses currently checked out from that pool. The list
refreshes automatically about every 10 seconds and shows the following columns:

* **User** – the user who checked out the license.
* **Host** – the host the license was checked out on.
* **Requested Product** / **Version** – the product and version requested.
* **Checked Out** – the number of licenses checked out.
* **Reserved** – the number reserved.
* **Time** – when the license was checked out.
* **Roam Return** – the roam return date, for roaming checkouts.
* **PID** – the process ID of the checkout.

***********************
Removing a Checkout
***********************

Whether a checkout can be removed depends on its type:

* **Roaming** checkouts cannot be revoked.
* **Temporary** checkouts can be removed only by users with **Edit** or **Admin** access. When you
  remove one, the portal warns you that the license is not actually revoked until it expires.
* **Normal** checkouts can be removed by users with **Manage** access or higher.

All checkout removals are recorded in the **Audit Log**.