about_Logging_Non-Windows

项目
11/06/2024

简短说明

PowerShell 记录引擎、提供程序和 cmdlet 的内部操作。

长说明

PowerShell 记录 PowerShell 操作的详细信息，例如启动和停止引擎以及启动和停止提供程序。它还记录有关 PowerShell 命令的详细信息。

有关在 Windows PowerShell 5.1 中日志记录的信息，请参阅 about_Logging。

PowerShell 日志的位置取决于目标平台。

在 Linux 上，PowerShell 会将日志记录到可以转发到 syslog 服务器的 系统日志。有关详细信息，请参阅 Linux 发行版的 man 页。
在 macOS 上，将使用 Apple 的统一日志记录系统。有关详细信息，请参阅 Apple 开发人员文档中关于日志记录的内容。

PowerShell 支持配置两类日志记录：

模块日志记录 - 记录指定模块成员的管道执行事件。必须为会话和特定模块启用模块日志记录。有关配置此日志记录的详细信息，请参阅 about_PowerShell_Config。

如果通过配置启用模块日志记录，可以通过设置模块的 LogPipelineExecutionDetails 属性的值，为会话中的特定模块启用和禁用日志记录。

例如，若要为 PSReadLine 模块启用模块日志记录，请执行以下操作：
```
$psrl = Get-Module PSReadLine
$psrl.LogPipelineExecutionDetails = $true
Get-Module PSReadline | Select-Object Name, LogPipelineExecutionDetails
```
```
Name       LogPipelineExecutionDetails
----       ---------------------------
PSReadLine                        True
```
脚本块日志记录 - 记录命令、脚本块、函数和脚本的处理，无论是以交互方式调用还是通过自动化调用。

启用脚本块日志记录后，PowerShell 会记录它处理的所有脚本块的内容。启用后，任何新的 PowerShell 会话都会记录此信息。

注意

建议在将脚本块日志记录用于诊断目的以外的任何内容时启用受保护的事件日志记录。有关详细信息，请参阅 about_PowerShell_Config。

在 Linux 或 macOS 上配置日志记录

Linux 和 macOS 上的日志记录配置存储在 powershell.config.json 文件中。 powershell.config.json 文件是驻留在 PowerShell $PSHOME 目录中的 JSON 格式化文件。如果此配置文件不存在，则需要创建该文件来更改默认设置。 PowerShell 的每次安装都使用该文件自己的副本。

默认情况下，PowerShell 允许 Informational 日志记录到 Operational 通道。如果需要其他日志输出（例如详细或启用分析日志输出），可以更改配置。

以下代码是一个示例配置：

{
    "ModuleLogging": {
        "EnableModuleLogging": false,
        "ModuleNames": [
            "PSReadLine",
            "PowerShellGet"
        ]
    },
    "ScriptBlockLogging": {
        "EnableScriptBlockInvocationLogging": true,
        "EnableScriptBlockLogging": true
    },
    "LogLevel": "verbose"
}

下面是用于配置 PowerShell 日志记录的属性列表。如果配置中未列出该属性，PowerShell 将使用默认值。

LogIdentity
- 值：<string name>、powershell
- 说明：日志记录时使用的名称。默认标识为 powershell。此值可用于判断 PowerShell 安装的两个实例（例如版本和 beta 版本）之间的差异。此值还用于将日志输出重定向到单独的文件。
LogChannels
- 值：Operational、Analytic
- 说明：要启用的通道。指定多个值时用逗号分隔。默认值是 Operational。
LogLevel
- 值：Always、Critical、Error、Warning、Informational、Verbose、Debug
- 说明：指定单个值。这些值按详细程度递增的顺序列出。选择的值启用其自身以及之前的所有值。默认值为 Informational。
LogKeywords
- 值：Runspace、Pipeline、Protocol、Transport、Host、Cmdlets、Serializer、Session、ManagedPlugin
- 描述：关键字提供将日志记录限制到 PowerShell 中特定组件的功能。默认情况下，所有关键字均已启用，更改此值仅对专门的故障排除有用。
PowerShellPolicies
- 说明： PowerShellPolicies 设置包含 ModuleLogging、 ProtectedEventLogging 和 ScriptBlockLogging 选项。有关详细信息，请参阅通用配置设置。

在 Linux 上查看 Journald 中的 PowerShell 日志数据

PowerShell 使用 Linux 发行版（如 Ubuntu 和 Red Hat Enterprise Linux (RHEL)）上的 journald 守护程序，将日志记录到 systemd 日志。

journald 守护进程以二进制格式存储日志消息。使用 journalctl 实用工具查询 PowerShell 条目的日志记录。

journalctl --grep powershell

journald 守护程序可以将日志消息转发到系统日志记录协议 (syslog) 服务器。 ForwardToSysLog如果要在 /etc/systemd/journald.conf Linux 系统上使用 syslog 日志记录，请在日记配置文件中启用该选项。这是许多 Linux 发行版的默认配置。

在 Linux 上查看 syslog 中的 PowerShell 日志数据

如果要在 Linux 系统上使用 syslog 日志记录，请使用 Linux 发行版的包管理器来安装 syslog 服务器，例如 rsyslog。一些 Linux 发行版（例如 Ubuntu）预安装了 rsyslog。

syslog 协议以标准化文本格式存储日志消息。可以使用任何文本处理实用工具来查询或查看 syslog 内容。

默认情况下，syslog 将日志条目写入以下位置：

对于基于 Debian 的发行版（包括 Ubuntu）：/var/log/syslog
对于基于 CentOS 的发行版：/var/log/messages

以下示例使用 cat 命令查询 Ubuntu 上的 PowerShell syslog 条目。

cat /var/log/syslog | grep -i powershell

Syslog 消息格式

Syslog 消息采用以下格式：

TIMESTAMP MACHINENAME powershell[PID]: (COMMITID:TID:CID)
  [EVENTID:TASK.OPCODE.LEVEL] MESSAGE

TIMESTAMP - 生成日志条目的日期/时间。
MACHINENAME - 生成日志的系统的名称。
PID - 写入日志条目的进程的进程 ID。
COMMITID - 用于生成内部版本的 git 提交 ID 或标记。
TID - 写入日志条目的线程 ID。
CID - 日志条目的十六进制通道标识符。
- 0x10 = 操作性
- 0x11 = 分析
EVENTID - 日志条目的事件标识符。
TASK - 事件项的任务标识符
OPCODE - 事件条目的操作码
LEVEL - 事件条目的日志级别
MESSAGE - 与事件条目关联的消息

EVENTID、TASK、OPCODE，LEVEL 与登录到 Windows 事件日志时使用的值相同。

将 PowerShell 日志消息写入单独的文件

还可以将 PowerShell 日志条目重定向到单独的文件。当 PowerShell 日志条目重定向到单独的文件时，它们不再记录到默认的 syslog 文件。

以下步骤将在 Ubuntu 上配置 PowerShell 日志条目以写入名为 powershell.log 的日志文件。

使用文本文件编辑器（例如 nano）在 /etc/rsyslog.d 目录中创建 PowerShell 日志配置的配置 (conf) 文件。为文件名添加小于默认值的数字的前缀。例如，40-powershell.conf，其中默认值为 50-default.conf。
```
sudo nano /etc/rsyslog.d/40-powershell.conf
```

在 40-powershell.conf 文件中添加以下信息：

:syslogtag, contains, "powershell[" /var/log/powershell.log
& stop

验证 /etc/rsyslog.conf 是否有新文件的 include 语句。它可能有一个包含它的泛型语句，例如：
```
$IncludeConfig /etc/rsyslog.d/*.conf
```
如果没有，则需要手动添加 include 语句。
验证是否已正确设置属性和权限。
```
ls -l /etc/rsyslog.d/40-powershell.conf
```
```
-rw-r--r-- 1 root root   67 Nov 28 12:51 40-powershell.conf
```
如果 40-powershell.conf 文件具有不同的所有权或权限，请完成以下步骤：
1. 将所有权设置为根。
```
sudo chown root:root /etc/rsyslog.d/40-powershell.conf
```
2. 设置访问权限：根具有读/写权限，用户具有读取权限。
```
sudo chmod 644 /etc/rsyslog.d/40-powershell.conf
```
重启 Syslog 服务。
```
sudo systemctl restart rsyslog.service
```
运行 pwsh 以生成要记录的 PowerShell 信息。
```
pwsh
```
注意

在重启 rsyslog 服务之前，不会创建/var/log/powershell.log 文件，PowerShell 会生成要记录的信息。
查询 powershell.log 文件，验证 PowerShell 信息是否已记录到新文件中。
```
cat /var/log/powershell.log
```

在 macOS 上查看 PowerShell 日志数据

PowerShell 将日志记录到 Apple 的统一日志记录系统，这是 macOS 的一项功能，允许在单个集中位置收集和存储系统和应用程序日志。

Apple 的统一日志记录系统以二进制格式存储日志消息。必须使用该工具 log 查询统一日志记录系统以获取 PowerShell 日志事件。 PowerShell 日志事件不会显示在 macOS 上的控制台 应用程序中。控制台应用专为早于统一日志记录系统的较旧的基于 syslog 的日志记录而设计。

在 macOS 上从命令行查看 PowerShell 日志数据

若要在 macOS 上通过命令行查看 PowerShell 日志数据，请在终端或其他 shell 主机应用程序中使用 log 命令。这些命令可以从 PowerShell、Z Shell 或 Bash 运行。

在以下示例中，log 命令用于显示系统上实时发生的日志数据。 process 参数仅筛选 pwsh 进程的日志数据。如果正在运行的多个 pwsh 实例，则 process 参数还接受进程 ID 作为其值。 level 参数显示指定级别和更低级别的消息。

log stream --predicate "subsystem == 'com.microsoft.powershell'" --level info

log show 命令可用于导出日志项。 log show 命令提供用于导出最后 N 个项、给定时间以来的项或给定时间跨度内的项的选项。

例如，以下命令导出自 9am on April 5, 2022 以来的项：

log show --start "2022-04-05 09:00:00" --predicate "subsystem == 'com.microsoft.powershell'"

有关详细信息，请运行 log show --help 以查看 log show 命令的帮助。

还可以以 JSON 格式输出日志数据，以便将事件数据转换为 PowerShell 对象。以下示例以 JSON 格式输出事件。该 ConvertFrom-Json cmdlet 用于将 JSON 数据转换为 PowerShell 对象存储在变量中 $logRecord 。

log show --predicate "subsystem == 'com.microsoft.powershell'" --style json |
    ConvertFrom-Json | Set-Variable logRecord

还可以考虑将日志保存到更安全的位置，例如安全信息和事件管理 (SIEM) 聚合器。使用 Microsoft Defender for Cloud Apps，可以在 Azure 中设置 SIEM。有关详细信息，请参阅通用 SIEM 集成。

macOS 上的 PowerShell 日志数据的模式和级别

默认情况下，在 macOS 上，PowerShell 子系统将信息级别消息记录到内存（模式），将默认级别消息记录到磁盘（持久）。可以使用 log config 命令更改此行为，以启用不同的模式和日志记录级别。

以下示例为 PowerShell 子系统启用信息级别日志记录和持久性：

sudo log config --subsystem com.microsoft.powershell --mode level:info,persist:info

使用 reset 参数将日志设置还原为 PowerShell 子系统的默认值：

sudo log config --subsystem com.microsoft.powershell --reset

另请参阅

对于 Linux syslog 和 rsyslog.conf 信息，请参阅 Linux 计算机的本地 man 页
有关 macOS 日志记录信息，请参阅 Apple 开发人员文档中关于日志记录的内容
对于 Windows，请参阅 about_Logging_Windows
泛型 SIEM 集成

通过