透過 Windows PowerShell 管理 Azure Stack Edge Pro FPGA 裝置

發行項
10/26/2023

Azure Stack Edge Pro FPGA 解決方案可讓您處理資料，並將其透過網路傳送至 Azure。本文說明 Azure Stack Edge Pro FPGA 裝置的一些設定和管理工作。您可以使用 Azure 入口網站、本機 Web UI 或 Windows PowerShell 介面來管理您的裝置。

本文著重于您使用 PowerShell 介面執行的工作。

本文包含下列程式：

連線至 Powershell 介面
建立支援套件
Upload certificate
重設裝置
檢視裝置資訊
取得計算記錄
監視和疑難排解計算模組

連線至 Powershell 介面

視用戶端的作業系統而定，遠端連線到裝置的程式會有所不同。

從 Windows 用戶端遠端連線

開始之前，請確定您的 Windows 用戶端正在執行 Windows PowerShell 5.0 或更新版本。

請遵循下列步驟從 Windows 用戶端遠端連線。

以系統管理員身分執行 Windows PowerShell 會話。
請確定 Windows 遠端系統管理服務正在您的用戶端上執行。在命令提示字元中，輸入：

winrm quickconfig

如需詳細資訊，請參閱 Windows 遠端系統管理的安裝和設定。
將變數指派給裝置 IP 位址。

$ip = 「 < device_ip > 」

將取代 <device_ip> 為您裝置的 IP 位址。
若要將裝置的 IP 位址新增至用戶端的受信任主機清單，請輸入下列命令：

Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force
在裝置上啟動 Windows PowerShell 會話：

Enter-PSSession -ComputerName $ip -Credential $ip\EdgeUser -ConfigurationName Minishell

出現提示時提供密碼。使用用來登入本機 Web UI 的相同密碼。預設的本機 Web UI 密碼為 Password1 。當您使用遠端 PowerShell 成功連線到裝置時，您會看到下列範例輸出：

Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.

PS C:\WINDOWS\system32> winrm quickconfig
WinRM service is already running on this machine.
PS C:\WINDOWS\system32> $ip = "10.100.10.10"
PS C:\WINDOWS\system32> Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force
PS C:\WINDOWS\system32> Enter-PSSession -ComputerName $ip -Credential $ip\EdgeUser -ConfigurationName Minishell

WARNING: The Windows PowerShell interface of your device is intended to be used only for the initial network configuration. Please engage Microsoft Support if you need to access this interface to troubleshoot any potential issues you may be experiencing. Changes made through this interface without involving Microsoft Support could result in an unsupported configuration.
[10.100.10.10]: PS>

從 Linux 用戶端遠端連線

在您將用來連線的 Linux 用戶端上：

從 GitHub 安裝適用于 Linux 的最新 PowerShell Core，以取得 SSH 遠端功能。
僅 gss-ntlmssp 從 NTLM 模組安裝套件。針對 Ubuntu 用戶端，請使用下列命令：
- sudo apt-get install gss-ntlmssp

如需詳細資訊，請移至透過 SSH 進行 PowerShell 遠端處理。

請遵循下列步驟從 NFS 用戶端遠端連線。

若要開啟 PowerShell 會話，請輸入：

pwsh
若要使用遠端用戶端進行連線，請輸入：

Enter-PSSession -ComputerName $ip -Authentication Negotiate -ConfigurationName Minishell -Credential ~\EdgeUser

出現提示時，請提供用來登入裝置的密碼。

注意

此程式不適用於 Mac OS。

建立支援套件

如果您遇到任何裝置問題，您可以從系統記錄建立支援套件。 Microsoft 支援服務使用此套件來針對問題進行疑難排解。請遵循下列步驟來建立支援套件：

連線裝置的 PowerShell 介面。

Get-HcsNodeSupportPackage使用命令來建立支援套件。 Cmdlet 的使用方式如下：

Get-HcsNodeSupportPackage [-Path] <string> [-Zip] [-ZipFileName <string>] [-Include {None | RegistryKeys | EtwLogs
        | PeriodicEtwLogs | LogFiles | DumpLog | Platform | FullDumps | MiniDumps | ClusterManagementLog | ClusterLog |
        UpdateLogs | CbsLogs | StorageCmdlets | ClusterCmdlets | ConfigurationCmdlets | KernelDump | RollbackLogs |
        Symbols | NetworkCmdlets | NetworkCmds | Fltmc | ClusterStorageLogs | UTElement | UTFlag | SmbWmiProvider |
        TimeCmds | LocalUILogs | ClusterHealthLogs | BcdeditCommand | BitLockerCommand | DirStats | ComputeRolesLogs |
        ComputeCmdlets | DeviceGuard | Manifests | MeasuredBootLogs | Stats | PeriodicStatLogs | MigrationLogs |
        RollbackSupportPackage | ArchivedLogs | Default}] [-MinimumTimestamp <datetime>] [-MaximumTimestamp <datetime>]
        [-IncludeArchived] [-IncludePeriodicStats] [-Credential <pscredential>]  [<CommonParameters>]

Cmdlet 會從您的裝置收集記錄，並將這些記錄複製到指定的網路或本機共用。

所使用的參數如下所示：

-Path - 指定要複製支援套件的網路或本機路徑。 (必要)
-Credential - 指定要存取受保護路徑的認證。
-Zip - 指定以產生 zip 檔案。
-Include - 指定要包含在支援套件中的元件。如果未指定， Default 則會假設為。
-IncludeArchived - 指定在支援套件中包含封存的記錄。
-IncludePeriodicStats - 指定在支援套件中包含定期統計資料記錄。

Upload certificate

適當的 SSL 憑證可確保您將加密資訊傳送至正確的伺服器。除了加密，憑證也允許進行驗證。您可以透過裝置的 PowerShell 介面上傳您自己的受信任 SSL 憑證。

連線至 PowerShell 介面。
Set-HcsCertificate使用 Cmdlet 上傳憑證。出現提示時，請提供下列參數：
- CertificateFilePath- 包含 .pfx 格式之憑證檔案 的共用路徑。
- CertificatePassword - 用來保護憑證的密碼。
- Credentials - 存取包含憑證之共用的使用者名稱。出現提示時，請提供網路共用密碼。
  
  下列範例顯示此 Cmdlet 的使用方式：
```
Set-HcsCertificate -Scope LocalWebUI -CertificateFilePath "\\myfileshare\certificates\mycert.pfx" -CertificatePassword "mypassword" -Credential "Username"
```

您也可以上傳 IoT Edge 憑證，以在您的 IoT Edge 裝置與可連線的下游裝置之間啟用安全連線。您需要安裝三個檔案（ .pem 格式）：

根 CA 憑證或擁有者 CA
裝置 CA 憑證
裝置私密金鑰

下列範例顯示此 Cmdlet 的用法，以安裝 IoT Edge 憑證：

Set-HcsCertificate -Scope IotEdge -RootCACertificateFilePath "\\hcfs\root-ca-cert.pem" -DeviceCertificateFilePath "\\hcfs\device-ca-cert.pem\" -DeviceKeyFilePath "\\hcfs\device-private-key.pem" -Credential "username"

當您執行此 Cmdlet 時，系統會提示您提供網路共用的密碼。

如需憑證的詳細資訊，請移至 Azure IoT Edge 憑證或在閘道上安裝憑證。

檢視裝置資訊

連線至 PowerShell 介面。

Get-HcsApplianceInfo使用來取得裝置的資訊。

下列範例顯示此 Cmdlet 的使用方式：

[10.100.10.10]: PS>Get-HcsApplianceInfo

Id                            : b2044bdb-56fd-4561-a90b-407b2a67bdfc
FriendlyName                  : DBE-NBSVFQR94S6
Name                          : DBE-NBSVFQR94S6
SerialNumber                  : HCS-NBSVFQR94S6
DeviceId                      : 40d7288d-cd28-481d-a1ea-87ba9e71ca6b
Model                         : Virtual
FriendlySoftwareVersion       : Data Box Gateway 1902
HcsVersion                    : 1.4.771.324
IsClustered                   : False
IsVirtual                     : True
LocalCapacityInMb             : 1964992
SystemState                   : Initialized
SystemStatus                  : Normal
Type                          : DataBoxGateway
CloudReadRateBytesPerSec      : 0
CloudWriteRateBytesPerSec     : 0
IsInitialPasswordSet          : True
FriendlySoftwareVersionNumber : 1902
UploadPolicy                  : All
DataDiskResiliencySettingName : Simple
ApplianceTypeFriendlyName     : Data Box Gateway
IsRegistered                  : False

以下是摘要一些重要裝置資訊的資料表：

參數	描述
FriendlyName	裝置在部署期間透過本機 Web UI 所設定的易記名稱。預設易記名稱是裝置序號。
SerialNumber	裝置序號是在處理站指派的唯一號碼。
Model	Azure Stack Edge 或資料箱閘道裝置的模型。此模型適用于 Azure Stack Edge 和適用于資料箱閘道的虛擬。
FriendlySoftwareVersion	對應至裝置軟體版本的易記字串。針對執行預覽的系統，易記的軟體版本會是 Data Box Edge 1902。
HcsVersion	在您的裝置上執行的 HCS 軟體版本。例如，對應至 Data Box Edge 1902 的 HCS 軟體版本是 1.4.771.324。
LocalCapacityInMb	裝置的本機容量總計，以 Megabits 為單位。
IsRegistered	這個值表示您的裝置是否已使用服務啟用。

重設裝置

若要重設裝置，您必須安全地抹除資料磁片和裝置開機磁片上的所有資料。

Reset-HcsAppliance使用 Cmdlet 來抹除資料磁片和開機磁片，或只抹除資料磁片。 SecureWipeBootDisk和 SecureWipeDataDisks 參數可讓您分別抹除開機磁片和資料磁片。

交換 SecureWipeBootDisk 器會抹除開機磁片，並使裝置無法使用。只有當裝置需要返回 Microsoft 時，才應該使用它。如需詳細資訊，請參閱將裝置傳回 Microsoft 。

如果您在本機 Web UI 中使用裝置重設，則只會安全地抹除資料磁片，但開機磁片會保持不變。開機磁碟包含裝置組態。

連線至 PowerShell 介面。

在命令提示字元中，輸入：

Reset-HcsAppliance -SecureWipeBootDisk -SecureWipeDataDisks

下列範例示範如何使用這個 Cmdlet：

[10.128.24.33]: PS>Reset-HcsAppliance -SecureWipeBootDisk -SecureWipeDataDisks

Confirm
Are you sure you want to perform this action?
Performing the operation "Reset-HcsAppliance" on target "ShouldProcess appliance".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [?] Help (default is "Y"): N

取得計算記錄

如果您的裝置上已設定計算角色，您也可以透過 PowerShell 介面取得計算記錄。

連線至 PowerShell 介面。
Get-AzureDataBoxEdgeComputeRoleLogs使用取得裝置的計算記錄。

下列範例顯示此 Cmdlet 的使用方式：
```
Get-AzureDataBoxEdgeComputeRoleLogs -Path "\\hcsfs\logs\myacct" -Credential "username" -FullLogCollection
```
以下是 Cmdlet 所使用的參數描述：
- Path：提供您要在其中建立計算記錄封裝之共用的網路路徑。
- Credential：提供網路共用的使用者名稱。當您執行此 Cmdlet 時，您必須提供共用密碼。
- FullLogCollection：此參數可確保記錄套件將包含所有計算記錄。根據預設，記錄套件只包含記錄的子集。

監視和疑難排解計算模組

在已設定計算角色的 Azure Stack Edge 裝置上，您可以使用兩組不同的命令對裝置進行疑難排解或監視。

使用 iotedge 命令。這些命令適用于您裝置的基本作業。
使用 dkrdbe 命令。這些命令適用于您裝置的大量作業集。

若要執行上述任一組命令，您必須連線至 PowerShell 介面。

使用 `iotedge` 命令

若要查看可用的命令清單，請連線到 PowerShell 介面並使用函 iotedge 式。

[10.100.10.10]: PS>iotedge -?                                                                                                                                                                                                 Usage: iotedge COMMAND

Commands:
   check
   list
   logs
   restart

[10.100.10.10]: PS>

下表簡短描述可用的 iotedge 命令：

命令	描述
`check`	針對常見的設定和連線問題執行自動化檢查
`list`	列出模組
`logs`	擷取模組的記錄
`restart`	停止並重新啟動模組

使用 `dkrdbe` 命令

若要查看可用的命令清單，請連線到 PowerShell 介面並使用函 dkrdbe 式。

[10.100.10.10]: PS>dkrdbe -?
Usage: dkrdbe COMMAND

Commands:
   image [prune]
   images
   inspect
   login
   logout
   logs
   port
   ps
   pull
   start
   stats
   stop
   system [df]
   top

[10.100.10.10]: PS>

下表簡短描述可用的 dkrdbe 命令：

命令	描述
`image`	管理映射。若要移除未使用的映射，請使用： `dkrdbe image prune -a -f`
`images`	列出影像
`inspect`	傳回 Docker 物件上的低階資訊
`login`	登入 Docker 登錄
`logout`	從 Docker 登錄登出
`logs`	擷取容器的記錄
`port`	列出埠對應或容器的特定對應
`ps`	列出容器
`pull`	從登錄提取映射或存放庫
`start`	啟動一或多個已停止的容器
`stats`	顯示容器（s）資源使用量統計資料的即時串流
`stop`	停止一或多個執行中的容器
`system`	管理 Docker
`top`	顯示容器的執行中進程

若要取得任何可用命令的說明，請使用 dkrdbe <command-name> --help 。

例如，若要瞭解命令的使用 port 方式，請輸入：

[10.100.10.10]: P> dkrdbe port --help

Usage:  dkr port CONTAINER [PRIVATE_PORT[/PROTO]]

List port mappings or a specific mapping for the container
[10.100.10.10]: P> dkrdbe login --help

Usage:  docker login [OPTIONS] [SERVER]

Log in to a Docker registry.
If no server is specified, the default is defined by the daemon.

Options:
  -p, --password string   Password
      --password-stdin    Take the password from stdin
  -u, --username string   Username
[10.100.10.10]: PS>

函式 dkrdbe 的可用命令會使用與用於一般 Docker 命令的參數相同。如需搭配 docker 命令使用的選項和參數，請移至使用 Docker 命令列。

檢查模組是否已成功部署

計算模組是已實作商務邏輯的容器。若要檢查計算模組是否已成功部署，請執行 ps 命令，並檢查容器是否正在執行（對應至計算模組）。

若要取得所有容器的清單（包括已暫停的容器），請執行 ps -a 命令。

[10.100.10.10]: P> dkrdbe ps -a
CONTAINER ID        IMAGE                                                COMMAND                   CREATED             STATUS              PORTS                                                                  NAMES
d99e2f91d9a8        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModuâ€¦"    2 days ago          Up 2 days                                                                                  movefile
0a06f6d605e9        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModuâ€¦"    2 days ago          Up 2 days                                                                                  filemove
2f8a36e629db        mcr.microsoft.com/azureiotedge-hub:1.0               "/bin/sh -c 'echo \"$â€¦"   2 days ago          Up 2 days           0.0.0.0:443->443/tcp, 0.0.0.0:5671->5671/tcp, 0.0.0.0:8883->8883/tcp   edgeHub
acce59f70d60        mcr.microsoft.com/azureiotedge-agent:1.0             "/bin/sh -c 'echo \"$â€¦"   2 days ago          Up 2 days                                                                                  edgeAgent
[10.100.10.10]: PS>

如果在建立容器映射或提取映射時發生錯誤，請執行 logs edgeAgent 。 EdgeAgent 是負責布建其他容器的 IoT Edge 執行時間容器。

由於 logs edgeAgent 會傾印所有記錄，因此查看最近錯誤的好方法是使用選項 --tail 20 。

[10.100.10.10]: PS>dkrdbe logs edgeAgent --tail 20
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Util.Uds.HttpUdsMessageHandler] - Connected socket /var/run/iotedge/mgmt.sock
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Util.Uds.HttpUdsMessageHandler] - Sending request http://mgmt.sock/modules?api-version=2018-06-28
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Core.Agent] - Getting edge agent config...
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Core.Agent] - Obtained edge agent config
2019-02-28 23:38:23.469 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Edgelet.ModuleManagementHttpClient] - Received a valid Http response from unix:///var/run/iotedge/mgmt.soc
k for List modules
--------------------CUT---------------------
--------------------CUT---------------------
08:28.1007774+00:00","restartCount":0,"lastRestartTimeUtc":"2019-02-26T20:08:28.1007774+00:00","runtimeStatus":"running","version":"1.0","status":"running","restartPolicy":"always
","type":"docker","settings":{"image":"edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64","imageHash":"sha256:47778be0602fb077d7bc2aaae9b0760fbfc7c058bf4df192f207ad6cbb96f7cc","c
reateOptions":"{\"HostConfig\":{\"Binds\":[\"/home/hcsshares/share4-dl460:/home/input\",\"/home/hcsshares/share4-iot:/home/output\"]}}"},"env":{}}
2019-02-28 23:38:28.480 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Core.Planners.HealthRestartPlanner] - HealthRestartPlanner created Plan, with 0 command(s).

取得容器記錄

若要取得特定容器的記錄，請先列出容器，然後取得您感興趣的容器記錄。

連線至 PowerShell 介面。

若要取得執行中的容器清單，請執行 ps 命令。

[10.100.10.10]: P> dkrdbe ps
CONTAINER ID        IMAGE                                                COMMAND                   CREATED             STATUS              PORTS                                                                  NAMES
d99e2f91d9a8        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModuâ€¦"    2 days ago          Up 2 days                                                                                  movefile
0a06f6d605e9        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModuâ€¦"    2 days ago          Up 2 days                                                                                  filemove
2f8a36e629db        mcr.microsoft.com/azureiotedge-hub:1.0               "/bin/sh -c 'echo \"$â€¦"   2 days ago          Up 2 days           0.0.0.0:443->443/tcp, 0.0.0.0:5671->5671/tcp, 0.0.0.0:8883->8883/tcp   edgeHub
acce59f70d60        mcr.microsoft.com/azureiotedge-agent:1.0             "/bin/sh -c 'echo \"$â€¦"   2 days ago          Up 2 days                                                                                  edgeAgent

記下您需要記錄之容器的容器識別碼。

若要取得特定容器的記錄，請執行 logs 提供容器識別碼的命令。

[10.100.10.10]: PS>dkrdbe logs d99e2f91d9a8
02/26/2019 18:21:45: Info: Opening module client connection.
02/26/2019 18:21:46: Info: Initializing with input: /home/input, output: /home/output.
02/26/2019 18:21:46: Info: IoT Hub module client initialized.
02/26/2019 18:22:24: Info: Received message: 1, SequenceNumber: 0 CorrelationId: , MessageId: 081886a07e694c4c8f245a80b96a252a Body: [{"ChangeType":"Created","ShareRelativeFilePath":"\\__Microsoft Data Box Edge__\\Upload\\Errors.xml","ShareName":"share4-dl460"}]
02/26/2019 18:22:24: Info: Moving input file: /home/input/__Microsoft Data Box Edge__/Upload/Errors.xml to /home/output/__Microsoft Data Box Edge__/Upload/Errors.xml
02/26/2019 18:22:24: Info: Processed event.
02/26/2019 18:23:38: Info: Received message: 2, SequenceNumber: 0 CorrelationId: , MessageId: 30714d005eb048e7a4e7e3c22048cf20 Body: [{"ChangeType":"Created","ShareRelativeFilePath":"\\f [10]","ShareName":"share4-dl460"}]
02/26/2019 18:23:38: Info: Moving input file: /home/input/f [10] to /home/output/f [10]
02/26/2019 18:23:38: Info: Processed event.

監視裝置的使用統計資料

若要監視裝置上的記憶體、CPU 使用量和 IO，請使用 stats 命令。

連線至 PowerShell 介面。

stats執行命令，以便停用即時串流，並只提取第一個結果。

dkrdbe stats --no-stream