test

Sun Desktop Manager 1.0 管理指南

第 3 章 使用指令行介面

本章提供有關 Sun Desktop Manager 指令行介面的相關資訊。

Desktop Manager CLI 簡介

此 CLI 可用於建立、處理、匯出、匯入和刪除配置設定檔。利用 Desktop Manager 的 GUI，CLI 可進行下列動作：

備註 –

CLI 不提供下列 GUI 功能的對等功能：

使用 CLI

呼叫 CLI 指令

CLI 由指令 pgtool 組成，該指令以單行指令模式進行作業，每次執行一條指令。pgtool 包含一組子指令、選項和運算元，這些將在指令摘要中說明。選項可以使用完整關鍵字或縮寫關鍵字進行指定。在以下的指令說明中使用了完整的關鍵字，但與指令對應的捷徑請見表 3–2。

CLI 需要的啟動資訊

需要啟動資訊，以尋找和查詢含有元素和設定檔的資料存放區。需要的啟動資訊包括伺服器、連接埠號、基底辨別名稱 (DN) 以及管理員的使用者名稱。此資訊可於指令行或在啟動檔案中指定。

啟動檔案

可從特性檔案中讀取啟動資訊。此檔案的位置可以透過 --file 選項在指令行中指定。

--file=<bootstrap file>：啟動檔案之完全合格的路徑。預設檔案為 $HOME/pgtool.properties。

範例：--file=/var/opt/apoc/cli.properties。

檔案的格式說明於「Sun Desktop Manager 1.0 安裝指南」中的附錄 A「 配置參數」。

啟動選項

可以使用 --url 和 --username 選項，在指令行中指定啟動程式。

--url=<url>：識別資料存放區的 URL 。URL 的格式為 ldap://<hostname>:<port>/<base name>，其中 <hostname> 是伺服器名稱 (預設為 localhost)、<port> 是伺服器的連接埠號 (預設為 389)，而 <base name> 是基底項目的辨別名稱。

範例：--url=ldap://server1.sun.com:399/o=apoc。

--username=<username>：管理員的使用者名稱，以後端儲存裝置使用的格式表示。然後，系統會提示管理員輸入密碼。如果未使用此選項，且管理員未使用 pgtool login 子指令，則系統將提示管理員輸入使用者名稱和密碼。

範例：--username=“jmonroe”。

使用使用者名稱和密碼驗證

每次執行指令時均需要使用者名稱和密碼。

透過 login 指令進行認證

CLI 提供一條 login 指令，以便將使用者名稱/密碼對儲存在管理員主目錄的憑證檔案中。檔案名稱為 .apocpass。.apocpass 檔案具有限定的存取權。

如果認證成功，則會將成對的使用者名稱/密碼項目增加至 .apocpass 檔案。此組合的金鑰由伺服器/連接埠/基底 DN 和使用者名稱所組成，如此一來，成對的使用者名稱/密碼便可儲存供相同檔案中其他的後端使用。

login 指令成功完成後，即可執行其他 CLI 指令，而不必指定使用者名稱或密碼。

如需有關如何使用 login 指令的詳細資訊，請參閱登入。

其他指令的認證

對於其他指令，CLI 會首先檢查是否存在目前使用者的 .apocpass 檔案。

如果該檔案不存在，系統將提示使用者輸入使用者名稱和密碼。如果該使用者名稱和密碼成功通過驗證，將執行指令。

如果憑證檔案的確存在且已於指令行中指定了使用者名稱，則 CLI 會尋找此主機、連接埠、基底 DN 和使用者名稱的項目。如果項目存在，將會使用儲存的使用者 DN 和密碼執行指令，否則將提示使用者輸入密碼。

如果未在指令行中指定使用者名稱，將會在 .apocpass 檔案中搜尋使用該主機/連接埠和基底 DN 之組合的關鍵字。如果存在此組合的唯一項目，將使用儲存的使用者 DN 和密碼執行指令。如果該項目不唯一，系統將提示使用者輸入使用者名稱。如果找到符合的項目，將使用儲存的使用者 DN 和密碼執行指令。如果沒有符合的項目，系統將提示使用者輸入密碼。

當系統提示使用者輸入密碼時，將使用此主機/連接埠/基底 DN 的組合之 .apocpass 檔案中的項目，認證使用者名稱和密碼。如果不存在這樣的項目，將使用匿名存取進行驗證。

執行指令

每次使用指令時均會建立和初始化與資料存放區的連線，然後在執行指令後結束該連線。如果指令結束並產生錯誤，則不會對配置設定檔套用任何變更。

表示元素

元素使用 LDAP 完整辨別名稱 (DN) 表示。

範例：uid=jmonroe,ou=People,o=apoc。

CLI 指令

本節說明 Desktop Manager CLI 功能的子指令。

備註 –

為達到向下相容的目的，CLI 使用 --entity 選項指定 Desktop Manager 使用者介面中現在稱為「元素」的項目。這些術語可以互換。沒有 --element 選項。

說明

若要取得所有可用 CLI 指令的清單，請鍵入 pgtool --help。

版本資訊

若要顯示版本資訊，請鍵入 pgtool --version。

新增

指定設定檔給元素。

語法

add [--scope=<user|host>] [--entity=<entity>] <profile name> <target entity>

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：設定檔所在的元素。若未指定，則預設為根組織或網域元素，視 --scope 選項而定。

<profile name>：要指定給元素的設定檔名稱。若在該層中沒有設定檔，或有多個設定檔具有此名稱和此範圍，則指令會發生錯誤並結束。

<target entity>：指定設定檔的元素。

範例 3–1 為元素增加設定檔

% pgtool add UserProfile1 cn=Role1,o=staff,o=apoc

位在根組織中的設定檔「UserProfile1」已指定給元素「cn=Role1,o=staff,o=apoc」。

建立

建立新的空白設定檔。

語法

create [--name=<profile name>] [--scope=<user|host>] [--entity=<entity>] [--priority=<priority>]

--name=<profile name>：要建立的設定檔名稱。如果使用此名稱和此範圍的設定檔已存在於在此層上，則指令會發生錯誤並結束。若未指定，則指令會預設使用系列 (例如「NewProfile」、「NewProfile2」、「NewProfile3」...) 中第一個可用的設定檔名稱。

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則指令會預設為使用者範圍。

--entity=<entity>：建立設定檔的元素。若未指定，則指令會預設為根組織或網域元素，視 --scope 選項而定。

--priority=<priority>：指定設定檔優先權的完全正整數。如果指定的優先權與此層中此範圍現有的設定檔優先權相同，則會忽略 priority 選項。若未指定，則建立的設定檔在此層中將有最高的優先權。

範例 3–2 建立新設定檔

% pgtool create --scope=host --name=NewHostProfile1

在網域根目錄中建立名為「NewHostProfile1」的新設定檔，其範圍為「主機」。

刪除

刪除設定檔。

語法

delete --name=<profile name> [--scope=<user|host>] [--entity=<entity>]

--name=<profile name>：要刪除的設定檔名稱。此為必要選項。若在該層中沒有設定檔，或有多個設定檔具有此名稱和此範圍，則指令會發生錯誤並結束。

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：設定檔所在的元素。若未指定，則預設為根組織或網域元素，視 --scope 選項而定。

範例 3–3 刪除設定檔

% pgtool delete --scope=host --name=renamedNewHostProfile1

刪除位於根網域的「renamedNewHostProfile1」設定檔。

匯出

使用壓縮檔格式，將某個設定檔中所包含的多個設定檔，匯出至指定的目標。

語法

export --name=<profile name> [--scope=<user|host>] [--entity=<entity>] <target>

--name=<profile name>：要匯出的設定檔名稱。此為必要選項。若在該層中沒有設定檔，或有多個設定檔具有此名稱和此範圍，則指令會發生錯誤並結束。

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：設定檔所在的元素。若未指定，則預設為根組織或網域元素，視 --scope 選項而定。

<target>：將匯出設定檔之壓縮檔的完整路徑。若路徑未指定任何檔案名稱，則檔案名稱預設為 <profile name>.zip。若無法寫入目標，則指令會發生錯誤並結束。

範例 3–4 匯出設定檔

% pgtool export --scope=host --name=HostProfile1 /tmp/newdir

已將位於根網域的「HostProfile1」匯出至建立於新目錄 /tmp/newdir 中的 HostProfile1.zip。

匯入

從指定的來源匯入以壓縮檔格式儲存的設定檔。來源包含要匯入至設定檔的多個設定檔。

語法

import [--name=<profile name>] [--scope=<user|host>] [--entity=<entity>] [--priority=<priority>] <source>

--name=<profile name>：要匯入的設定檔名稱。若未指定，則預設為 .zip 來源檔案的名稱。如果此層中已存在具有此名稱與範圍的設定檔，則會覆寫該設定檔。

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：設定檔所在的元素。若未指定，則預設為根組織或網域元素，視 --scope 選項而定。

--priority=<priority>：指定設定檔優先權的完全正整數。若指定的優先權與此層中此範圍現有的設定檔優先權相同，則會忽略此選項。若未指定，則匯入的設定檔將在此層中具有最高的優先權。

<source>：包含要匯入的設定檔之壓縮檔的完整路徑。

範例 3–5 匯入設定檔

% pgtool import --scope=host --name=NewHostProfile1 --priority=7 /tmp/HostProfile1.zip

已從 HostProfile1.zip 匯入位於根網域中名為「NewHostProfile1」而範圍為「主機」且優先權為「7」的設定檔。

清單

列出所有設定檔或元素/設定檔指定。

若 --name 選項與 --entity 選項均未指定，則會列出所有使用者或主機設定檔，視 --scope 選項而定。

若指定 --name 選項，則會列出所有指定給此設定檔的元素。

若指定 --entity 選項，則會列出所有指定給該元素的設定檔。

語法

list [--scope=<user|host>] [--entity=<entity>] [--name =<profile name>]

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：若指定 --name 選項，則為設定檔所在的元素。否則，會指定列出設定檔之元素。若之前未指定，則預設為根組織或網域元素，視 --scope 選項而定。

--name=<profile name>：將會列出指定元素的設定檔名稱。若在該層中沒有設定檔，或有多個設定檔具有此名稱和此範圍，則指令會發生錯誤並結束。

範例 3–6 列出指定

% pgtool list

列出指定給根組織的設定檔。

% pgtool list --scope=host --name=HostProfile1

列出指定給位於根網域中之設定檔「HostProfile1」的元素。

登入

成功通過資料存放區的認證之後，儲存後端資料存放區的使用者名稱和密碼。則此使用者名稱和密碼在將來可以用於呼叫 pgtool。

憑證儲存在管理員主目錄中名為 .apocpass 的檔案中。如果此檔案已存在且它不具有正確的許可權，則指令將發生錯誤並結束。

若已指定了使用者名稱，系統將提示管理員輸入密碼，否則系統將提示管理員輸入使用者名稱和密碼。使用對資料存放區的匿名存取，驗證該使用者名稱和密碼。若不支援匿名存取，系統將提示管理員輸入已授權的使用者名稱和密碼。如果已授權使用者名稱的驗證失敗，則指令將發生錯誤並結束。

一經認證，成對的使用者名稱/密碼項目即會儲存在使用主機/連接埠/基底 DN 和使用者名稱之組合所組成的金鑰之管理員的 .apocpass 檔案中。如此一來成對的使用者名稱/密碼便可儲存以供相同檔案的其他後端使用。

啟動資訊可使用指令指定，例如使用 --file 選項指出找到資訊的檔案，或使用 --url 選項直接指定此資訊。如需有關啟動程式的更多資訊，請參閱CLI 需要的啟動資訊。

如果沒有啟動資訊可用，或者無法建立憑證檔案，則指令會發生錯誤並結束。

若已成功建立了憑證檔案，則不必使用此後端儲存裝置為後續的 pgtool 指令指定使用者名稱和密碼。將會使用儲存在憑證檔案中的使用者名稱和密碼詳細資訊。

語法

login [--username=<username>] [--file=<bootstrap file>] [--url=<url>]

--username=<username>：後端儲存裝置所使用之格式的管理員使用者名稱，例如「jmonroe」。

--file=<bootstrap file>：啟動檔案之完全合格的路徑。預設檔案為 $HOME/pgtool.properties。此選項與 --url 選項不相容。

--url=<url>：識別資料存放區的 URL 。URL 的格式為 ldap://<hostname>:<port>/<base name>，其中 <hostname> 是伺服器名稱 (預設為 localhost)、<port> 是伺服器的連接埠號 (預設為 389)，而 <base name> 是基底項目的辨別名稱。

範例 3–7 登入

% pgtool login --username=jmonroe [Enter the correct password when prompted]

使用「jmonroe」和「密碼」之項目所建立的檔案 ~/.apocpass，檔案具有權限 600。要連接之後端的相關資訊，可於預設啟動檔案 ~/pgtool.properties 中找到。

修改

變更設定檔的優先權。

語法

modify [--scope=<user|host>] [--entity=<entity>] <profile name> <priority>

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：設定檔所在的元素。若未指定，則預設為根組織或網域元素，視 --scope 選項而定。

<profile name>：要變更其優先權的設定檔名稱。若在該層中沒有設定檔，或有多個設定檔具有此名稱和此範圍，則指令會發生錯誤並結束。

<priority>：指定設定檔優先權的完全正整數。若指定的優先權與此層上此範圍的現有設定檔之優先權相同，則指令會發生錯誤並結束。

範例 3–8 變更設定檔的優先權

% pgtool modify UserProfile1 15

將位於根組織中之「UserProfile1」的優先權變更為 15。

移除

從元素取消指定設定檔。

語法

remove [--scope=<user|host>] [--entity=<entity>] <profile name> <target entity>

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：設定檔所在的元素。若未指定，則預設為根組織或網域元素，視 --scope 選項而定。

<profile name>：要從目標元素取消指定的設定檔名稱。

<target entity>：要取消指定設定檔的元素。

範例 3–9 從元素取消指定設定檔

% pgtool remove UserProfile1 cn=Role1,o=staff,o=apoc

位在根組織中的設定檔「UserProfile1」已從元素「cn=Role1,o=staff,o=apoc」中取消指定。

重新命名

重新命名設定檔。

語法

rename [--scope=<user|host>] [--entity=<entity>] <profile name> <newname>

--scope=<user|host>：設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。

--entity=<entity>：設定檔所在的元素。若未指定，則預設為根組織或網域元素，視 --scope 選項而定。

<profile name>：要重新命名之設定檔目前的名稱。

<newname>：設定檔的新名稱。如果使用此名稱和範圍的設定檔已存在於在此層上，則指令會發生錯誤並結束。

範例 3–10 重新命名設定檔

% pgtool rename NewUserProfile2 renamedNewUserProfile2

已將位於根組織中的「NewUserProfile2」重新命名為「renamedNewUserProfile2」。

指令摘要

表 3–1 指令

指令 

說明 

add

為元素指定設定檔。 

create

建立新的空白設定檔。 

delete

刪除設定檔。 

export

使用壓縮檔格式，將設定檔中所包含的多個設定檔，匯出至指定的目標。 

import

從指定的來源匯入以壓縮檔格式儲存的設定檔。來源包含要匯入至設定檔的多個設定檔。 

list

列出所有設定檔或要指定給元素的設定檔，或已指定設定檔的元素。 

login

將此後端資料存放區的使用者名稱和密碼，儲存在管理員的主目錄之檔案內。則此使用者名稱和密碼在將來可以用於呼叫 pgtool。

modify

變更設定檔的優先權。 

remove

從元素取消指定設定檔。 

rename

重新命名設定檔。 

表 3–2 選項

選項 

說明 

-b <base name>, --base=<base name>, 已停用

後端儲存裝置的根項目。此基底項目的格式由使用的後端儲存裝置來確定。例如，根項目為 o=apoc 的 LDAP 後端儲存裝置：--base o=apoc。

已停用：改用 --url 選項

-e <entity>, --entity=<entity>

表示使用者、角色、組織、主機或網域元素。該元素的項目格式由使用的後端儲存裝置決定。例如，具有使用者「jmonroe」的 LDAP 後端儲存裝置：-e uid=jmonroe,ou=People,o=Staff,o=apoc 。

-f <file>, --file=<file>

詳細列出執行此指令所用之啟動資訊的檔案之完全合格路徑。例如：-f /var/opt/apoc/cli.properties。

-h <hostname>, --hostname=<hostname> , 已停用

後端儲存裝置之主機名稱。例如：--host=server1.sun.com。

已停用：改用 --url 選項

-i <priority>, --priority=<priority>

指定設定檔優先權的完全正整數。例如： -i 12。

-l <url>, --url=<url>

識別資料存放區的 URL 。URL 的格式為 ldap://<hostname>:<port>/<base name>，其中 <hostname> 是伺服器名稱 (預設為 localhost)、<port> 是伺服器的連接埠號 (預設為 389)，而 <base name> 是基底項目的辨別名稱。例如：--url=ldap://server1.sun.com:399/o=apoc。

-m <name>, --name=<name>

設定檔的名稱。例如：--name=UserProfile1。

-p <port>, --port=<port>, 已停用

後端儲存裝置的連接埠號。例如：-p 399。

已停用：改用 --url 選項

-s <scope>, --scope=<scope>

設定檔的範圍，可以是使用者或主機。若未指定，則預設為使用者範圍。例如：--scope=host。

-t <type>, --type=<type>, 已停用

後端儲存裝置的類型。此項預設為 LDAP。例如：-t LDAP。

已停用：改用 --url 選項

-u <username>, --username=<username>

管理員的使用者名稱，以後端儲存裝置使用的格式表示。然後，系統會提示管理員輸入密碼。如果未使用此選項，且管理員未使用 pgtool login 子指令，則系統將提示管理員輸入使用者名稱和密碼。例如：--username=jmonroe。

-?, --help

顯示說明資訊 

-V, --version

顯示版本資訊。