about_Logging_Non-Windows
Short description
PowerShell logs internal operations from the engine, providers, and cmdlets.
Long description
PowerShell logs details of PowerShell operations, such as starting and stopping the engine and starting and stopping providers. It also logs details about PowerShell commands.
The location of PowerShell logs is dependent on the target platform.
- On Linux, PowerShell logs to the systemd journal that can forward to a
syslog server. For more information, see the
man
pages for your Linux distribution. - On macOS, the os_log logging system is used. For more information, see os_log developer documentation.
Configuring logging on Linux or macOS
The configuration for logging on Linux and macOS is stored in the
powershell.config.json
file. The powershell.config.json
file is a JSON
formatted file residing in the PowerShell $PSHOME
directory. If this
configuration file doesn't exist, you'll need to create it to change the
default settings. Each installation of PowerShell uses its own copy of this
file.
By default, PowerShell enables Informational
logging to the Operational
channel. You can change the configuration if you require additional log output,
such as verbose or enabling analytic log output.
The following code is an example configuration:
{
"ScriptBlockLogging": {
"EnableScriptBlockInvocationLogging": true,
"EnableScriptBlockLogging": true
},
"ModuleLogging": {
"EnableModuleLogging": false,
"ModuleNames": [
"PSReadLine",
"PowerShellGet"
]
},
"LogLevel": "verbose"
}
The following is a list of properties for configuring PowerShell logging. If the property isn't listed in the configuration, PowerShell uses the default value.
- LogIdentity
- Values:
<string name>
,powershell
- Description: The name to use when logging. The default identity is
powershell
. This value can be used to tell the difference between two instances of a PowerShell installation, such as a release and beta version. This value is also used to redirect log output to a separate file.
- Values:
- LogChannels
- Values:
Operational
,Analytic
- Description: The channels to enable. Separate the values with a comma when
specifying more than one. The default value is
Operational
.
- Values:
- LogLevel
- Values:
Always
,Critical
,Error
,Warning
,Informational
,Verbose
,Debug
- Description: Specify a single value. The values are listed in increasing
order of verbosity. The value you choose enables itself and all the values
before it. The default value is
Informational
.
- Values:
- LogKeywords
- Values:
Runspace
,Pipeline
,Protocol
,Transport
,Host
,Cmdlets
,Serializer
,Session
,ManagedPlugin
- Description: Keywords provide the ability to limit logging to specific components within PowerShell. By default, all keywords are enabled and change this value is only useful for specialized troubleshooting.
- Values:
Viewing PowerShell log data in journald on Linux
PowerShell logs to the systemd journal using the journald daemon on Linux distributions such as Ubuntu and Red Hat Enterprise Linux (RHEL).
The journald daemon stores log messages in a binary format. Use the
journalctl
utility to query the journal log for PowerShell entries.
journalctl --grep powershell
The journald daemon can forward log messages to a System Logging Protocol
(syslog) server. Enable the ForwardToSysLog
option in the
/etc/systemd/journald.conf
journald configuration file if you want to
use syslog logging on your Linux system. This is the default configuration
for many Linux distributions.
Viewing PowerShell log data in syslog on Linux
Use the package manager for your Linux distribution to install a syslog server such as rsyslog if you want to use syslog logging on your Linux system. Some Linux distributions such as Ubuntu preinstall rsyslog.
The syslog protocol stores log messages in a standardized text format. You can use any text processing utility to query or view syslog content.
By default, syslog writes log entries to the following location:
- On Debian-based distributions, including Ubuntu:
/var/log/syslog
- On RHEL-based distributions:
/var/log/messages
The following example uses the cat
command to query for PowerShell syslog
entries on Ubuntu.
cat /var/log/syslog | grep -i powershell
Syslog message format
Syslog messages have the following format:
TIMESTAMP MACHINENAME powershell[PID]: (COMMITID:TID:CID)
[EVENTID:TASK.OPCODE.LEVEL] MESSAGE
- TIMESTAMP - A date/time when the log entry was produced.
- MACHINENAME - The name of the system where the log was produced.
- PID - The process ID of the process that wrote the log entry.
- COMMITID - The git commit ID or tag used to produce the build.
- TID - The thread ID of the thread that wrote the log entry.
- CID - The hex channel identifier of the log entry.
- 0x10 = Operational
- 0x11 = Analytic
- EVENTID - The event identifier of the log entry.
- TASK - The task identifier for the event entry
- OPCODE - The opcode for the event entry
- LEVEL - The log level for the event entry
- MESSAGE - The message associated with the event entry
EVENTID, TASK, OPCODE, and LEVEL are the same values as used when logging to the Windows event log.
Write PowerShell log message to a separate file
It's also possible to redirect the PowerShell log entries to a separate file. When the PowerShell log entries are redirected to a separate file, they're no longer logged to the default syslog file.
The following steps configure PowerShell log entries on Ubuntu to write to a
log file named powershell.log
.
Create a config (
conf
) file for the PowerShell log configuration in the/etc/rsyslog.d
directory using a text file editor such asnano
. Prefix the filename with a number that's less than the default. For example,40-powershell.conf
where the default is50-default.conf
.sudo nano /etc/rsyslog.d/40-powershell.conf
Add the following information to the
40-powershell.conf
file::syslogtag, contains, "powershell[" /var/log/powershell.log & stop
Verify that
/etc/rsyslog.conf
has an include statement for the new file. It may have a generic statement that includes it, such as:$IncludeConfig /etc/rsyslog.d/*.conf
If it doesn't, you'll need to add an include statement manually.
Verify the attributes and permissions are set appropriately.
ls -l /etc/rsyslog.d/40-powershell.conf
-rw-r--r-- 1 root root 67 Nov 28 12:51 40-powershell.conf
If your
40-powershell.conf
file has different ownership or permissions, complete the following steps:Set ownership to root.
sudo chown root:root /etc/rsyslog.d/40-powershell.conf
Set access permissions: root has read/write, users have read.
sudo chmod 644 /etc/rsyslog.d/40-powershell.conf
Restart the rsyslog service.
sudo systemctl restart rsyslog.service
Run
pwsh
to generate PowerShell information to log.pwsh
Note
The
/var/log/powershell.log
file isn't created until the rsyslog service is restarted and PowerShell generates information to log.Query the
powershell.log
file to verify PowerShell information is being logged to the new file.cat /var/log/powershell.log
Viewing PowerShell log output on macOS
The easiest method for viewing PowerShell log output on macOS is using the Console application.
- Search for the Console application and launch it.
- Select the Machine name under Devices.
- In the Search field, enter
pwsh
for the PowerShell main binary. - Change the search filter from
Any
toProcess
. - Perform the operations.
- Optionally, save the search for future use.
The process ID for a running instance of PowerShell is stored in the $PID
.
variable. Use the following steps to filter on a specific process instance of
PowerShell in the Console.
- Enter the process ID for
pwsh
in the Search field. - Change the search filter to
PID
. - Perform the operations.
To view PowerShell log output from a command line, use the log
command.
sudo log stream --predicate 'process == "pwsh"' --info
Persisting PowerShell log output
By default, PowerShell uses the default memory-only logging on macOS. This
behavior can be changed to enable persistence using the log config
command.
The following script enables info level logging and persistence:
log config --subsystem com.microsoft.powershell --mode=persist:info,level:info
The following command reverts PowerShell logging to the default state:
log config --subsystem com.microsoft.powershell --mode=persist:default,level:default
After persistence is enabled, the log show
command can be used to export log
items. The command provides options for exporting the last N items, items since
a given time, or items within a given time span.
For example, the following command exports items since
9am on April 5 of 2018
:
log show --info --start "2018-04-05 09:00:00" --predicate "process = 'pwsh'"
You can get help for log
by running log show --help
for additional details.
Tip
When executing any of the log commands from a PowerShell prompt or script, use double quotes around the entire predicate string and single quotes within. This avoids the need to escape double quote characters within the predicate string.
You may also want to consider saving the event logs to a more secure location such as Security Information and Event Management (SIEM) aggregator. Using Microsoft Defender for Cloud Apps, you can set up SIEM in Azure. For more information, see Generic SIEM integration.
See also
- For Linux syslog and rsyslog.conf information, refer to the Linux
computer's local
man
pages - For macOS os_log information, see os_log developer documentation
- For Windows, see about_Logging_Windows
- Generic SIEM integration
Feedback
Submit and view feedback for