.. _lcm-machine-credential:

Machine Credentials
===================
Machine Credentials contain the necessary information for logging into remote
hosts as well as how to escalate privileges (sudo/su).

.. container:: api-toc

    ===================================== ====================================
    :ref:`managing-machine-credentials`   URL
    ===================================== ====================================
    Get a machine credential object by ID :http:method:`get-machine-credential-object`
    Get a list of machine credentials     :http:method:`get-machine-credential-list`
    Create a machine credential           :http:method:`post-machine-credential-object` 
    Update a machine credential           :http:method:`put-machine-credential-object`
    Delete a machine credential           :http:method:`delete-repository-object`
    ===================================== ====================================

.. _managing-machine-credentials:

Managing Machine Credentials
----------------------------

.. http:response:: Machine Credential

    .. code-block:: js

        {
            "id": <value>,
            "name": <value>,
            "login-name": <value>,
            "login-password": <value>,
            "ssh-private-key": <value>,
            "ssh-unlock": <value>
            "become-mode": <value>, 
            "become-user": <value>,
            "become-password": <value>,
            "use-ssh-keys": <value>,
            "comment": <value>
        }

    ============================== =========================================
    Property                       Description of Values
    ============================== =========================================
    id                             A UUID for the Machine Credential.
    name                           A human-readable name for the credential. Required.
    login-name                     The username that will be used to log in to target nodes over SSH.
                                   Required.
    login-password                 The password that will be used to log in to target nodes over SSH, if
                                   using password authentication.
    ssh-private-key                The private-key that will be used to log in to target nodes over SSH,
                                   if using key-based authentication. Must be in OpenSSH format, which is
                                   commonly used when creating keys with OpenSSH's ssh-keygen tool.                
    ssh-unlock                     The ssh passphrase required to unlock the key, if the private key requires one.
    become-mode                    The privilege-escalation mechanism to obtain super-user privileges on
                                   target nodes. Can be sudo, su, or direct (if login-name
                                   already has super-user privs). Defaults to direct.
    become-user                    The name of the super-user on target nodes whose privileges will be assumed.
                                   Required if become-mode is sudo or su. Defaults to root.
    become-password                The password that will be used in response to sudo or su prompts on target
                                   nodes. Required if the become-mode is sudo or su and the target node prompts
                                   for passwords.
    use-ssh-keys                   Ignored. Optional.
    comment                        A comment that describes the credential. Optional.
    ============================== =========================================

    Note that, for security reasons, passwords and other sensitive fields are not returned in response objects.

.. http:method:: GET /api/v1/lcm/machine_credentials/{id}
    :label-name: get-machine-credential-object
    :title: GET /api/v1/lcm/machine_credentials/{id}

    Gets a specific machine credentials record by ID.

    :arg id: A :http:response:`machine-credential` ID.

    Returns a :http:response:`machine-credential` object.

    **Example**:

    .. code-block:: bash

        curl http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3

    Output:

    .. code-block:: js

        {
        
            "become-user": null,
            "become-mode": "sudo",
            "created-on": "2016-06-20T21:00:41.405Z",
            "type": "machine-credential",
            "related-resources": {
                "datacenters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/datacenters/",
                "nodes": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/nodes/",
                "clusters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/clusters/"
            },
            "modified-by": "system",
            "modified-on": "2016-06-20T21:00:41.405Z",
            "name": "my cluster creds",
            "use-ssh-keys": false,
            "comment": null,
            "login-user": "johndoe",
            "id": "ba908cb4-9116-4cf9-abe6-694ad75b70d3",
            "href": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3",
            "created-by": "system"
        
        }

.. http:method:: GET /api/v1/lcm/machine_credentials/
    :label-name: get-machine-credential-list
    :title: GET /api/v1/lcm/machine_credentials/

    Gets a paginated list of all :http:response:`machine-credential` records. See :ref:`lcm-pagination` for
    an overview of the query string parameters that can be used.

    **Example**:

    .. code-block:: bash

        curl http://localhost:8888/api/v1/lcm/machine_credentials/

    Output:

    .. code-block:: js

        {
            "next": null,
            "previous": null,
            "last": 1,
            "count": 1,
            "per-page": 50,
            "current": 1,
            "results": [
                {
                    "created-on": "2016-06-20T21:00:41.405Z",
                    "type": "machine-credential",
                    "related-resources": {
                        "datacenters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/datacenters/",
                        "nodes": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/nodes/",
                        "clusters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/clusters/"
                    },
                    "modified-on": "2016-06-20T21:00:41.405Z",
                    "name": "my cluster creds",
                    "login-user": "johndoe",
                    "id": "ba908cb4-9116-4cf9-abe6-694ad75b70d3",
                    "href": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3"
                }
            ]
        }

.. http:method:: POST /api/v1/lcm/machine_credentials/
    :label-name: post-machine-credential-object
    :title: POST /api/v1/lcm/machine_credentials/

    Creates a new machine credential object.

    :body: A :http:response:`machine-credential` object (with no ID property).

    Returns the newly created :http:response:`machine-credential` object.

    **Example**:

    Input:

    .. code-block:: js

        {
            "become-mode":"sudo",
            "use-ssh-keys":false,
            "name":"my cluster creds",
            "login-user":"johndoe",
            "login-password":"foo",
            "become-password":"foo",
            "ssh-private-key":null,
            "ssh-unlock":null,
            "become-user":null
        }
          
    .. code-block:: bash

       curl -X POST -d '<example input>' http://localhost:8888/api/v1/lcm/machine_credentials/

    Output:

    .. code-block:: js

        {
            "become-user": null,
            "become-mode": "sudo",
            "created-on": "2016-06-20T21:00:41.405Z",
            "type": "machine-credential",
            "related-resources": {
                "datacenters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/datacenters/",
                "nodes": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/nodes/",
                "clusters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/clusters/"
            },
            "modified-by": "system",
            "modified-on": "2016-06-20T21:00:41.405Z",
            "name": "my cluster creds",
            "use-ssh-keys": false,
            "comment": null,
            "login-user": "johndoe",
            "id":
            "ba908cb4-9116-4cf9-abe6-694ad75b70d3",
            "href": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3",
            "created-by": "system"
        }

.. http:method:: PUT /api/v1/lcm/machine_credentials/{id}
    :label-name: put-machine-credential-object
    :title: PUT /api/v1/lcm/machine_credentials/{id}

    Update an existing machine credential record by ID.

    :arg id: A :http:response:`machine-credential` ID.

    Returns the updated :http:response:`machine-credential` object.

    **Example**:

    Input:

    .. code-block:: js

        {
            "become-user":null,
            "become-mode":"sudo",
            "name":"my cluster creds",
            "use-ssh-keys":false,
            "comment":null,
            "login-user":"janedoe",
            "id":"ba908cb4-9116-4cf9-abe6-694ad75b70d3",
            "created-by":"system",
            "login-password":"blah",
            "become-password":"blah",
            "ssh-private-key":null,
            "ssh-unlock":null
        }

    .. code-block:: bash

        curl -X PUT -d '<example input>' http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3

    Output:

    .. code-block:: js

        {
            "become-user": null,
            "become-mode": "sudo",
            "created-on": "2016-06-20T21:00:41.405Z",
            "type": "machine-credential",
            "related-resources": {
                "datacenters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/datacenters/",
                "nodes": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/nodes/",
                "clusters": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3/clusters/"
            },
            "modified-by": "system",
            "modified-on": "2016-06-20T21:09:08.308Z",
            "name": "my cluster creds",
            "use-ssh-keys": false,
            "comment": null,
            "login-user": "janedoe",
            "id": "ba908cb4-9116-4cf9-abe6-694ad75b70d3",
            "href": "http://localhost:8888/api/v1/lcm/machine_credentials/ba908cb4-9116-4cf9-abe6-694ad75b70d3",
            "created-by": "system"
        }

.. http:method:: DELETE /api/v1/lcm/machine_credentials/{id}
    :label-name: delete-machine-credential-object
    :title: DELETE /api/v1/lcm/machine_credentials/{id}

    Delete an existing machine credential record by ID. This is subject to foreign key constraint violations.

    :arg id: A :http:response:`machine-credential` ID.

    Returns the IDs of the deleted objects.

    **Example**:

    .. code-block:: bash

        curl -X DELETE http://localhost:8888/api/v1/lcm/machine_credentials/5d756e26-4e49-41bc-8d5a-0e5c1dbfdc98

    Output:

    .. code-block:: js

        {"deleted": {"machine-credential": ["ba908cb4-9116-4cf9-abe6-694ad75b70d3"]}}