unicornidm-tool(8)
===================

概要
-----

::

    unicornidm-tool <resource> <command> [<args>]
    unicornidm-tool <command> [<args>]

説明
------

このツールは Unicorn ID Manager に対してユーザー追加やグループ追加などの操作を
行うための機能を提供します。このツールを利用するためには :ref:`unicornidm-tool-conf`
に設定を記述する必要があります。

*resource* は *user* 、 *group* 、 *admin* および *role* のいずれかを選択します。

*command* は *resource* に対してどのような操作を実行するかを指定します。

*args* はそれぞれの *resource* と *command* の組み合わせに対する引数やオプションです。

.. _unicornidm-tool-conf:

unicornidm-tool に対する設定
----------------------------

:doc:`unicornidm-conf` に以下の内容を追記してください。

::

    [client]
    server_url = https://localhost:443/
    admin_name = test-admin
    admin_password_file = /path/to/test-admin-password
    uid = unicornidm
    gid = unicornidm
    timezone = Asia/Tokyo

*[client]* はクライアント設定のセクションが開始されることを示します。

.. program:: unicornidm.conf[client]

.. option:: server_url

    Unicorn ID Manager が稼働するサーバーの URL です。

.. option:: admin_name

    Unicorn ID Manager に接続するための管理者名です。
    設定しておくと、 :option:`unicornidm-tool -A` オプションを省略できます。
.. option:: admin_password_file

    :option:`admin_name` のパスワードを格納したファイル名です。
    設定しておくと、 :option:`unicornidm-tool -P` オプションを省略できます。

.. option:: timezone

    :program:`unicornidm-tool result2` の出力の時刻のタイムゾーンを設定できます。

*uid* と *gid* は **unicornidm-tool admin** か **unicornidm-tool role** を実行する
際に利用されます。 Unicorn ID Manager の実行ユーザー/グループを指定してください。


それぞれのコマンドの詳細
-------------------------

unicornidm-tool 共通のオプション
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

以下のオプションは **unicornidm-tool** のほとんどのサブコマンドで指定できます。

.. program:: unicornidm-tool

.. option:: -A <文字列>, --admin-name <文字列>

    コマンドを実行する UIDM の管理者の名前を指定します。
    指定しない場合は :option:`unicornidm.conf[client] admin_name` が使われます。
    それも設定されていない場合はプロンプトが表示されます。


.. option:: -P <ファイルパス>, --admin-password-file <ファイルパス>

    コマンドを実行する UIDM の管理者のパスワードを指定します。
    指定しない場合は :option:`unicornidm.conf[client] admin_password_file` が使われます。
    それも設定されていない場合はプロンプトが表示されます。

ユーザー/グループに対して操作を実行するコマンド
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

    $ unicornidm-tool resource-type operation-name target csv-filepath [options]
    5a30a5a964989b433b33b1f2

:program:`unicornidm-tool resource-type operation-name` コマンドはバックエンドに対してユーザー/グループ情報を変更する操作を実行します。

操作が全て UIDM サーバー側で完了した後に実行した操作の *submissionID* を1つ出力し終了します。
結果を見たい場合には :program:`unicornidm-tool result2` コマンドに出力された *submissionID* を渡してください。以下はその例です。

.. code-block:: console

    $ unicornidm-tool result2 operations Target1 --filter submissionID=5a30a5a964989b433b33b1f2

以下が引数、オプションです。

.. program:: unicornidm-tool resource-type operation-name

.. option:: resource-type

    ``user`` か ``group`` を指定してください。

.. option:: operation-name

    **user の場合**
        - ``add``
        - ``modify``
        - ``rename``
        - ``delete``
        - ``changepassword``
        - ``enable``
        - ``disable``

    **group の場合**
        - ``add``
        - ``modify``
        - ``rename``
        - ``delete``
        - ``addmembers``
        - ``deletemembers``


.. option:: target

    操作を実行するターゲットを指定してください。

.. option:: csv-filepath

    CSVファイルのパスを指定してください。
    CSVファイルの詳細については :ref:`operation-csv-format` を参照ください。

.. option:: -b <カンマ区切りの文字列>, --backends <カンマ区切りの文字列>

    操作を実行するバックエンドを指定してください。

    例: ``ldap-backend1,ad-backend1``

    指定しない場合は、ターゲットに属する全てのバックエンドで操作が実行されます。

.. option:: -A <文字列>, --admin-name <文字列>
    :noindex:

.. option:: -P <ファイルパス>, --admin-password-file <ファイルパス>
    :noindex:

ユーザー/グループの情報を取得するコマンド
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

    $ unicornidm-tool user getpassword [options] target

自動生成されたユーザーのパスワードを取得します。
一度取得したパスワードを再度取得することはできません。

    ::

        Arguments:
        TARGET      対象のターゲット

        Options:
        -A, --admin-name TEXT           管理者の名前
        -P, --admin-password-file TEXT  管理者のパスワードを格納したファイル

unicornidm-tool user list [OPTIONS] TARGET
    ユーザー一覧を取得します。


    ::

        Arguments:
        TARGET                              対象のターゲット

        Options:
        -A, --admin-name TEXT               管理者の名前
        -P, --admin-password-file TEXT      管理者のパスワードを格納したファイル
        -p, --page INTEGER                  リストのページ番号
        --sort-by KEY                       KEY に基づいてソート
        --sort-order [ascending|descending] ソートを昇順にするか降順にするか
        --refresh                           キャッシュをリフレッシュして取得
        --limit INTEGER                     1 ページあたりの表示数
                                            (0 の場合、すべて表示 (時間がかかります))
        --filter TEXT                       検索フィルター

unicornidm-tool group list [OPTIONS] TARGET
    グループ一覧を取得します。


    ::

        Arguments:
        TARGET                              対象のターゲット

        Options:
        -A, --admin-name TEXT               管理者の名前
        -P, --admin-password-file TEXT      管理者のパスワードを格納したファイル
        -p, --page INTEGER                  リストのページ番号
        --sort-by KEY                       KEY に基づいてソート
        --sort-order [ascending|descending] ソートを昇順にするか降順にするか
        --refresh                           キャッシュをリフレッシュして取得
        --limit INTEGER                     1 ページあたりの表示数
                                            (0 の場合、すべて表示 (時間がかかります))
        --filter TEXT                       検索フィルター

unicornidm-tool group listmembers [OPTIONS] TARGET GROUP_NAME
    グループのメンバー一覧を取得します。


    ::

        Arguments:
        TARGET                              対象のターゲット
        GROUP_NAME                          対象のグループ

        Options:
        -A, --admin-name TEXT               管理者の名前
        -P, --admin-password-file TEXT      管理者のパスワードを格納したファイル
        --refresh                           キャッシュをリフレッシュして取得


結果取得用の操作
^^^^^^^^^^^^^^^^

:program:`unicornidm-tool result2` は操作結果を JSON 形式で取得します。

.. code-block:: console

    $ unicornidm-tool result2 type target [options]

引数、およびオプションは以下です。

.. program:: unicornidm-tool result2

.. option:: type

    ``submissions`` か ``operations`` を指定してください。前者がサマリーで後者が詳細です。

.. option:: target

    ターゲットID を指定してください。

.. option:: -f <文字列>, --filter <文字列>

    取得する結果を絞り込みます。
    複数個指定できます。

    個々のオプションは ``-f <フィールド名>=<値>`` の形式である必要があります。
    ``<フィールド名>`` にはこのコマンドの出力として返ってくる JSON 内のフィールド名を指定してください。
    フィールドの型によって ``<値>`` の形式が異なります。

    **文字列**
        文字列をそのまま指定してください。
        指定するフィールドによって部分一致か全体一致か、大文字小文字を区別しないかなどが変わります。

    **整数**
        整数を指定してください。

    **真偽値**
        真偽値 ``true`` で検索したい場合、文字列 ``true`` （大文字小文字は区別しない）を指定してください。
        それ以外の文字列の場合は真偽値 ``false`` で検索します。

    **日時**
        ``<日時>,<日時>`` とコンマで2つ日時を指定することで範囲検索ができます。
        上限を指定しないときには ``<日時>,`` と指定し、
        下限を指定しないときには ``,<日時>`` と指定してください。

        `<日時>` のフォーマットは ISO 8601 形式で指定してください。
        例: ``2017-12-13T11:48:25+09:00``

        日付よりも細かい単位は省略しても構いません。
        例: ``2017-12-13``

        タイムゾーンは省略すると :doc:`unicornidm-conf` の ``[client]`` セクションで指定したタイムゾーンが使われます。

    **IPアドレス**
        範囲検索をしたいときには CIDR 形式を利用してください。
        例: ``192.168.0.0/16``

        特定のアドレスを検索したいときには `/` 移行を除いてください。
        例: ``192.168.0.1``

.. option:: -s <文字列>, --sort <文字列>

    結果をソートします。
    複数回指定できます。

    ``-s <フィールド名>`` または ``-s -<フィールド名>`` の形式で指定してください。
    前者は昇順になり、後者は降順になります。


.. option:: -l <整数>, --limit <整数>

    結果の最大取得数を設定します。
    デフォルトは ``10000`` です。

.. option:: -o <整数>, --offset <整数>

    検索して得られた結果のうち、先頭 <整数> 分だけを出力しません。
    デフォルトは ``0`` です。

.. option:: -A <文字列>, --admin-name <文字列>
    :noindex:

.. option:: -P <ファイルパス>, --admin-password-file <ファイルパス>
    :noindex:


.. versionadded:: 3.15.0
    :program:`unicornidm-tool result2` コマンドが追加されました。

unicornidm-tool result [OPTIONS] TARGET
    リソースに対する操作結果をCSV形式で取得します。

    .. deprecated:: 3.20.0
        代わりに :program:`unicornidm-tool result2` を使ってください。
        CSV 形式で結果を取得したい場合は、 JSON から CSV に変換するスクリプトを用意してください。


    ::

        Arguments:
        TARGET                          対象のターゲット

        Opions:
        -A, --admin-name TEXT          管理者の名前
        -P, --admin-password-file TEXT 管理者のパスワードを格納したファイル
        -p, --page INTEGER             リストのページ番号
        --limit INTEGER                1 ページあたりの表示数
                                       (0 の場合、すべて表示 (時間がかかります))
        --filter TEXT                  検索フィルター

        --old                          UnicornIDM 3.14.0 にアップデートする前に発生した操作の結果を取得します


管理者に関する操作
^^^^^^^^^^^^^^^^^^^

ローカルサーバーの Unicorn ID Manager 上の管理者を操作します。
これらのコマンドは Unicorn ID Manager を起動してから行う必要があります。


unicornidm-tool admin add [OPTIONS] NAME
    管理者を追加します。

    ::

        Arguments:
        NAME                           追加する管理者の名前

        Options:
        --password TEXT                追加する管理者のパスワード
                                       (指定がない場合プロンプト又は標準入力から入力)
        -r, --role TEXT                追加する管理者のロール
                                       (デフォルトは SuperView)

unicornidm-tool admin changepassword [OPTIONS] NAME
    管理者のパスワードを変更します。

    ::

        Arguments:
        NAME                           パスワードを変更する管理者の名前

        Options:
        --password TEXT                パスワードを変更する管理者の新しいパスワード
                                       (指定がない場合プロンプトから入力)

unicornidm-tool admin changerole [OPTIONS] NAME ROLE
    管理者のロールを変更します。

    ::

        Arguments:
        NAME                           ロールを変更する管理者の名前
        ROLE                           ロール名


unicornidm-tool admin delete [OPTIONS] NAME
    管理者を削除します。

    ::

        Arguments:
        NAME                           削除する管理者の名前
                                       (デフォルトは False)

unicornidm-tool admin list [OPTIONS]
    管理者の一覧を取得します。



ロールに関する操作
^^^^^^^^^^^^^^^^^^^

ローカルサーバーの Unicorn ID Manager 上のロールを操作します。
これらのコマンドは Unicorn ID Manager を起動してから行う必要があります。

unicornidm-tool role add [OPTIONS] ROLE_FILE
    ロールを追加します。

    ::

        Arguments:
        ROLE_FILE                      追加するロールの情報を格納したファイル

    ROLE_FILE は JSON フォーマットのファイルで、以下のようなファイルです。
    この JSON オブジェクトには必ず **name** と **privileges** を含まなければなりません。
    また、 **privileges** は Array 型で、それぞれの要素は **target** と **actions**
    を含むオブジェクトでなければなりません。

    ::

        {
          "name": "role_name",
          "privileges": [
            {
              "target": "target_name",
              "actions": [
                "user_list",
                "user_modify",
                "user_change_password"
              ]
            }
          ]
        }

    指定可能なアクションは以下のとおりです。 **privileges** 内の **actions** に
    ここで指定したアクションを含めることで、作成されるロールはこれらのアクションを
    実行することが可能になります。

    .. list-table:: 指定可能なアクション一覧
        :header-rows: 1

        * - アクション名
          - アクションの説明
        * - user_list
          - ユーザー一覧参照操作
        * - user_add
          - ユーザー作成操作
        * - user_modify
          - ユーザー更新操作
        * - user_enable
          - ユーザー有効化操作
        * - user_disable
          - ユーザー無効化操作
        * - user_delete
          - ユーザー削除操作
        * - user_rename
          - ユーザーのリネーム操作
        * - user_change_password
          - ユーザーのパスワード変更操作
        * - group_list
          - グループ一覧参照操作
        * - group_add
          - グループ作成操作
        * - group_modify
          - グループ更新操作
        * - group_delete
          - グループ削除操作
        * - group_rename
          - グループのリネーム操作
        * - group_add_members
          - グループへのメンバー追加操作
        * - group_delete_members
          - グループからのメンバー削除操作
        * - result
          - 結果参照操作
        * - get_password
          - ランダム生成されたパスワードの取得操作

    **privileges** 内のオブジェクトである、 **target** には *
    を指定することが可能です。これにより、すべてのターゲットに対する権限を
    指定できます。

    **privileges** 内のオブジェクトである、 **actions** 内に *
    を含めた場合、すべてのアクションを操作可能な権限を指定できます。

    .. versionadded:: 3.7.9

        v3.7.9 で **actions** に * を含めることができるようになりました。


unicornidm-tool role delete [OPTIONS] ROLE_NAME
    ロールを削除します。

    ::

        Arguments:
        ROLE_NAME                      削除するロールの名前
                                       (デフォルトは False)

unicornidm-tool role list [OPTIONS]
    ロールの一覧を取得します。


バックアップ・リストアに関する操作
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Unicorn ID Manager が内部のデータベースに保持している管理者情報、ロール情報及び監査ログを
バックアップ、復元するコマンドです。
これらのコマンドは Unicorn ID Manager を起動してから行う必要があります。

unicornidm-tool backup [OPTIONS]
    バックアップを取得します。

    ::

        Options:
        -d, --backup-directory TEXT    バックアップデータ保存先ディレクトリー
                                       (デフォルトは LOCALSTATE_DIRECTORY/backup)
        -c, --backup-count INTEGER     バックアップ世代数 (デフォルトは 30)

unicornidm-tool restore BACKUP_ARCHIVE
    ``BACKUP_ARCHIVE`` からデータを内部データベースに復元します。

    ::

        Arguments:
        BACKUP_ARCHIVE      unicornidm-tool backup でバックアップしたアーカイブファイル
