about_Logging_Non-Windows

简短说明

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) 服务器。 如果要在 Linux 系统上使用 syslog 日志记录，请在 /etc/systemd/journald.confjournald 配置文件中启用 ForwardToSysLog 选项。 这是许多 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 的日志文件。

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

   sudo nano /etc/rsyslog.d/40-powershell.conf
   

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

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

3. 验证 /etc/rsyslog.conf 是否有新文件的 include 语句。 它可能有一个包含它的泛型语句，例如：

   $IncludeConfig /etc/rsyslog.d/*.conf
   

   如果没有，则需要手动添加 include 语句。

4. 验证是否已正确设置属性和权限。

   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
      

5. 重启 Syslog 服务。

   sudo systemctl restart rsyslog.service
   

6. 运行 pwsh 以生成要记录的 PowerShell 信息。

   pwsh
   

   注意

   在重启 rsyslog 服务之前，不会创建/var/log/powershell.log 文件，PowerShell 会生成要记录的信息。

7. 查询 powershell.log 文件，验证 PowerShell 信息是否已记录到新文件中。

   cat /var/log/powershell.log
   

在 macOS 上查看 PowerShell 日志数据

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

Apple 的统一日志记录系统以二进制格式存储日志消息。 使用控制台应用或日志工具查询 PowerShell 条目的统一日志记录系统。

在 macOS 上的控制台应用程序中查看 PowerShell 日志数据

macOS 上的控制台应用程序是一个实用工具，提供用于查看日志数据的图形用户界面。 默认情况下，控制台应用程序包含在 macOS 中，可通过在“应用程序”文件夹中打开“实用工具”文件夹进行访问。

按照以下步骤在 macOS 上的控制台应用程序中查看 PowerShell 日志数据：

1. 搜索控制台应用程序并启动它。
2. 在“设备”下选择计算机名称。
3. 在“搜索”字段中，输入 PowerShell 主二进制文件的 pwsh，然后按返回。
4. 将搜索筛选器从 Any 更改为 Process。
5. 单击开始。
6. 运行 pwsh 以生成要记录的 PowerShell 信息。

正在运行的 PowerShell 实例的进程 ID 存储在 $PID 变量中。 使用以下步骤筛选控制台应用程序中 PowerShell 的特定进程实例。

1. 运行 pwsh 实例。
2. 在上一步中启动的 PowerShell 实例中运行 $PID 以确定其进程 ID。
3. 在“搜索”字段中输入 pwsh 的进程 ID，然后按返回。
4. 将搜索筛选器从 Any 更改为 PID。
5. 单击开始。
6. 生成要从第一步中启动的 PowerShell 实例记录的 PowerShell 信息。

有关详细信息，请参阅在 Mac 上的控制台中查看日志消息。

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

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

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

log stream --process pwsh --level info

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

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

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

log show --info --start "2022-04-05 09:00:00" --process pwsh

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

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

另请参阅

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