about_PowerShell_Config

about_PowerShell_Config

PowerShell의 설정 파일(powershell.config.json)이 뭘 하는 건지, 어디에 두는 건지, 그리고 각 설정 키가 실제로 어떤 변화를 만들어 내는지 하나씩 살펴볼게요. 예전에는 레지스트리로 설정을 관리했는데, 지금 PowerShell에서는 이 JSON 파일이 그 자리를 대신해요.

출처: about_PowerShell_Config — Microsoft Learn

본문

간단한 설명

PowerShell의 설정 파일이에요. 예전 레지스트리 기반 설정을 대체합니다.

자세한 설명

powershell.config.json 파일에 PowerShell의 구성 설정이 들어 있어요. PowerShell은 시작할 때 이 설정을 불러오고, 런타임에도 값을 바꿀 수 있어요. 다만 모든 키가 모든 플랫폼에 적용되지는 않아요.

주의할 점이 하나 있어요. 설정 파일에 알 수 없는 키나 잘못된 값이 있으면 그냥 무시돼요. 그런데 powershell.config.json 자체가 잘못된 JSON이 되면? 그 경우엔 PowerShell이 대화형 세션을 시작할 수 없어요. 이렇게 되면 설정 파일을 바로 고쳐야 해요.

설정 키 요약

powershell.config.json 파일에는 다음 키들을 넣을 수 있어요.

  • DisableImplicitWinCompat
  • WindowsPowerShellCompatibilityModuleDenyList
  • WindowsPowerShellCompatibilityNoClobberModuleList
  • ExperimentalFeatures
  • LogChannels
  • LogIdentity
  • LogKeywords
  • LogLevel
  • Microsoft.PowerShell:ExecutionPolicy
  • PSModulePath
  • PowerShellPolicies
  • ExecutionPolicy
  • ConsoleSessionConfiguration
  • ModuleLogging
  • ProtectedEventLogging
  • ScriptBlockLogging
  • ScriptExecution
  • Transcription
  • UpdatableHelp

설정의 적용 범위

구성 설정은 모든 사용자(all users) 기준으로 정의할 수도 있고, 개별 사용자(user) 단위로도 정의할 수 있어요.

범위 우선순위

몇 가지 특별한 경우를 빼면, CurrentUser 단계에서 정의한 설정이 AllUsers 단계의 설정보다 우선해요.

Windows 시스템에서는 이렇게 돼요.

  • Windows 그룹 정책(Group Policy)으로 관리되는 설정이 설정 파일의 값보다 우선해요.
  • 실행 정책(Execution Policy)은 범위 단계 설정을 지원해요.

모든 플랫폼에서 공통으로:

  • $env:PSModulePath의 최종 값은 두 범위의 PSModulePath 키 값을 합친(merge) 결과예요.

AllUsers(공유) 구성

$PSHOME 디렉터리에 있는 powershell.config.json 파일은 해당 PowerShell 설치본에서 실행되는 모든 세션의 구성을 정의해요.

참고로, $PSHOME 위치는 실행 중인 System.Management.Automation.dll 어셈블리와 같은 디렉터리로 정해져요. 호스팅된 PowerShell SDK 인스턴스에도 동일하게 적용돼요.

CurrentUser(사용자별) 구성

사용자 단위로도 PowerShell을 구성할 수 있어요. 파일을 사용자 범위 구성 디렉터리에 두면 돼요. 사용자 구성 디렉터리는 플랫폼에 관계없이 다음 명령으로 찾을 수 있어요.

Split-Path $PROFILE.CurrentUserCurrentHost

Windows 전용 설정

다음 설정은 Windows 플랫폼에서만 적용돼요.

  • DisableImplicitWinCompat
  • WindowsPowerShellCompatibilityModuleDenyList
  • WindowsPowerShellCompatibilityNoClobberModuleList
  • Microsoft.PowerShell:ExecutionPolicy
  • PowerShellPolicies
  • ScriptExecution

DisableImplicitWinCompat

이 값을 true로 설정하면 Windows PowerShell 호환(Compatibility) 기능이 꺼져요. Windows PowerShell 호환 기능은 PowerShell 7이 Windows PowerShell 5.1 모듈을 호환 모드로 불러올 수 있게 해 주는 기능이에요.

더 자세한 내용은 about_Windows_PowerShell_Compatibility를 참고하세요.

WindowsPowerShellCompatibilityModuleDenyList

Windows PowerShell 호환 기능에서 제외하고 싶은 모듈 이름 목록을 담는 배열이에요.

더 자세한 내용은 about_Windows_PowerShell_Compatibility를 참고하세요.

WindowsPowerShellCompatibilityNoClobberModuleList

Windows PowerShell 5.1 버전 모듈이 로드되면서 덮어써지면(clobber) 안 되는 모듈 이름 목록이에요.

더 자세한 내용은 about_Windows_PowerShell_Compatibility를 참고하세요.

Microsoft.PowerShell:ExecutionPolicy

PowerShell 세션의 실행 정책을 설정해요. 어떤 스크립트를 실행할 수 있는지가 여기서 결정돼요. 기본적으로 PowerShell은 기존 실행 정책을 그대로 사용해요.

AllUsers 구성에서는 LocalMachine 실행 정책을 설정하고, CurrentUser 구성에서는 CurrentUser 실행 정책을 설정해요.

다음 예시는 PowerShell의 실행 정책을 RemoteSigned로 설정해요.

{
  "Microsoft.PowerShell:ExecutionPolicy": "RemoteSigned"
}

더 자세한 내용은 about_Execution_Policies를 참고하세요.

비 Windows 플랫폼 설정

다음 설정은 Linux와 macOS 플랫폼에서만 적용돼요.

Linux와 macOS에서 PowerShell의 로깅을 구성하려면 다음 키를 사용해요.

  • LogChannels
  • LogIdentity
  • LogKeywords
  • LogLevel

비 Windows 시스템의 PowerShell 로깅에 대한 자세한 설명은 about_Logging_Non-Windows를 참고하세요.

공통 구성 설정

다음 설정은 지원되는 모든 플랫폼에서 사용할 수 있어요.

  • ExperimentalFeatures
  • PSModulePath
  • PowerShellPolicies

ExperimentalFeatures

PowerShell에서 활성화할 실험 기능의 이름 목록이에요. 기본값은 빈 배열이에요.

다음 예시는 PowerShell이 시작될 때 PSCommandNotFoundSuggestion과 PSSubsystemPluginModel 실험 기능을 활성화해요.

{
  "ExperimentalFeatures": [
    "PSCommandNotFoundSuggestion",
    "PSSubsystemPluginModel"
  ]
}

실험 기능에 대해 더 자세히 알고 싶다면 Using experimental features를 참고하세요.

PSModulePath

이 세션의 PSModulePath 설정을 덮어써요. 현재 사용자용 구성이면 CurrentUser 모듈 경로를, 모든 사용자용 구성이면 AllUsers 모듈 경로를 설정해요.

잠깐, 주의할 점이 있어요. 여기서 AllUsers나 CurrentUser 모듈 경로를 설정한다고 해서, Install-Module 같은 PowerShellGet cmdlet의 기본 설치 위치가 바뀌는 건 아니에요. 그 cmdlet들은 항상 기본 모듈 경로를 사용해요.

값을 설정하지 않으면 PowerShell은 해당 모듈 경로 설정의 기본값을 사용해요. 이 기본값에 대한 자세한 내용은 about_PSModulePath를 참고하세요.

이 설정은 % 문자 사이에 환경 변수를 넣어서 사용할 수 있어요. 예를 들면 "%HOME%\Documents\PowerShell\Modules"처럼요. Windows 명령 셸(Command Shell)이 허용하는 방식과 똑같아요. 이 문법은 Linux와 macOS에서도 적용돼요. 아래 예시를 볼게요.

Windows 환경용 PSModulePath 구성 예시:

{
  "PSModulePath": "C:\\Program Files\\PowerShell\\7\\Modules"
}

macOS 또는 Linux 환경용 구성 예시:

{
  "PSModulePath": "/opt/powershell/6/Modules"
}

PSModulePath 구성에 환경 변수를 넣은 예시예요. HOME 환경 변수와 / 디렉터리 구분자를 사용해서, 이 문법은 Windows, macOS, Linux 모두에서 동작해요.

{
  "PSModulePath": "%HOME%/Documents/PowerShell/Modules"
}

이 예시는 macOS와 Linux에서만 동작하는 환경 변수를 사용해요.

{
  "PSModulePath": "%XDG_CONFIG_HOME%/powershell/Modules"
}

참고로, PSModulePath 구성에는 PowerShell 변수를 넣을 수 없어요. 그리고 PSModulePath 구성은 Linux와 macOS에서 대소문자를 구분해요. 또 해당 플랫폼에 맞는 올바른 디렉터리 구분자를 써야 해요. macOS와 Linux에서는 /, Windows에서는 /와 \ 모두 동작해요.

PowerShellPolicies

PowerShellPolicies는 다양한 설정을 담는 키-값 쌍으로 된 JSON 객체예요. ScriptExecution 설정을 제외한 모든 설정은 Windows, Linux, macOS 플랫폼에서 사용할 수 있어요.

PowerShellPolicies에는 다음 하위 키가 들어 있어요.

  • ConsoleSessionConfiguration
  • ModuleLogging
  • ProtectedEventLogging
  • ScriptBlockLogging
  • ScriptExecution
  • Transcription
  • UpdatableHelp

Windows에서는 이 설정들을 Windows 그룹 정책(Group Policy)으로 관리할 수 있어요. 그룹 정책 설정이 우선해요. 그룹 정책으로 값이 정해지지 않았다면, PowerShell이 범위 우선순위(scope precedence) 순서대로 JSON 파일의 값을 적용해요.

Windows 시스템에서는 이런 설정을 그룹 정책으로 관리하는 걸 권장해요. 더 자세한 내용은 about_Group_Policy_Settings를 참고하세요.

ConsoleSessionConfiguration

이 설정은 모든 PowerShell 세션에 사용할 세션 구성을 지정해요. 로컬 머신에 등록된 아무 엔드포인트나 될 수 있어요. 기본 PowerShell 원격 엔드포인트부터 특정 사용자 역할 기능을 가진 사용자 지정 엔드포인트까지요.

이 키에는 두 개의 하위 키가 있어요.

  • EnableConsoleSessionConfiguration — 세션 구성을 활성화하려면 값을 true로 설정해요. 기본값은 false예요.
  • ConsoleSessionConfigurationName — PowerShell이 실행될 구성 엔드포인트의 이름을 지정해요. 기본적으로 정의된 세션은 없어요.
{
  "ConsoleSessionConfiguration": {
    "EnableConsoleSessionConfiguration": false,
    "ConsoleSessionConfigurationName" : []
  }
}

더 자세한 내용은 about_Session_Configurations를 참고하세요.

ModuleLogging

이 설정은 PowerShell 모듈의 로깅 동작을 제어해요. 두 개의 하위 키가 있어요.

  • EnableModuleLogging — 모듈 로깅을 활성화하려면 값을 true로 설정해요. 활성화하면 지정된 모듈의 멤버에서 발생하는 파이프라인 실행 이벤트가 PowerShell 로그 파일에 기록돼요.
  • ModuleNames — 로깅할 모듈의 이름을 지정해요.
{
  "ModuleLogging": {
    "EnableModuleLogging": true,
    "ModuleNames" : [
        "PSReadLine",
        "PowerShellGet"
    ]
  }
}
ProtectedEventLogging

이 설정은 보호된 이벤트 로깅(Protected Event Logging)을 구성할 수 있게 해 줘요. 두 개의 하위 키가 있어요.

  • EnableProtectedEventLogging — 이 정책 설정을 활성화하면, 지원하는 구성 요소가 로그에 쓰기 전에 제공한 인증서로 로그 데이터를 암호화해요. 데이터는 CMS(Cryptographic Message Syntax) 표준으로 암호화돼요. 인증서의 개인 키에 접근할 수 있다면 Unprotect-CmsMessage로 이 암호화된 메시지를 복호화할 수 있어요.
  • EncryptionCertificate — 암호화에 사용할 인증서 이름 목록을 제공해요.
{
  "ProtectedEventLogging": {
    "EnableProtectedEventLogging": false,
    "EncryptionCertificate": [
      "Joe"
    ]
  }
}
ScriptBlockLogging

이 설정은 모든 PowerShell 스크립트 입력의 로깅을 제어해요. 두 개의 하위 키가 있어요.

  • EnableScriptBlockLogging — 이 정책 설정을 활성화하면, PowerShell이 대화형으로 호출되든 자동화를 통해서든 명령, 스크립트블록, 함수, 스크립트의 처리 과정을 로깅해요.
  • EnableScriptBlockInvocationLogging — 스크립트블록의 시작/종료 이벤트 로깅을 활성화해요.
"ScriptBlockLogging": {
  "EnableScriptBlockInvocationLogging": true,
  "EnableScriptBlockLogging": false
}
ScriptExecution

ScriptExecution 설정은 PowerShell 실행 정책을 설정할 때 사용해요. 앞에서 설명한 Microsoft.PowrShell:ExecutionPolicy 설정보다 우선해요.

{
    "PowerShellPolicies": {
        "ScriptExecution": {
            "ExecutionPolicy": "RemoteSigned"
        }
    }
}

이 설정은 Windows 전용이에요.

Transcription

이 정책 설정은 PowerShell 명령의 입력과 출력을 텍스트 기반 트랜스크립트로 캡처할 수 있게 해 줘요. 활성화하면 PowerShell이 모든 PowerShell 세션에 대해 전사(transcription)를 켜요.

이 설정은 PowerShell에서 트랜스크립션이 동작하는 방식을 제어해요. 하위 키는 세 개예요.

  • EnableTranscripting — 활성화하면 PowerShell이 구성된 위치에 트랜스크립션 로그 파일을 만들어요.
  • EnableInvocationHeader — 기본적으로 PowerShell은 트랜스크립션 로그 파일 맨 위에 헤더를 포함해요. 이 설정으로 헤더를 끌 수 있어요.
  • OutputDirectory — 트랜스크립션 로그 파일을 기본 위치 대신 중앙 위치에 모을 수 있게 해 줘요.
{
    "Transcription": {
        "EnableTranscripting": true,
        "EnableInvocationHeader": true,
        "OutputDirectory": "C:\\tmp"
      }
}

더 자세한 내용은 Start-Transcript를 참고하세요.

UpdatableHelp

이 정책 설정은 Update-Help cmdlet의 SourcePath 매개 변수 기본값을 설정할 수 있게 해 줘요. 이 기본값은 SourcePath 매개 변수로 다른 값을 지정하면 덮어쓸 수 있어요.

{
    "UpdatableHelp": {
      "DefaultSourcePath": "F:\\temp"
    }
}

더 알아보기