Impostazioni dell'app

Le impostazioni dell'applicazione si trovano nel file appsettings.json all'interno della directory di installazione. Questo file definisce varie impostazioni che può applicare a PowerShell Universal. Sebbene sia possibile modificare direttamente questo file, si consiglia di utilizzare uno dei metodi seguenti per rendere persistenti le impostazioni, poiché il file appsettings.json nella directory di installazione verrà sovrascritto durante gli aggiornamenti.

Quando viene installato dall'MSI, la directory di installazione di PowerShell Universal è ${env:ProgramFiles(x86)}\Universal.

AppSettings.json in ProgramData

Può creare un file appsettings.json nella cartella $Env:ProgramData\PowerShellUniversal. Può utilizzare un sottoinsieme delle impostazioni presenti nel file appsettings.json. Ad esempio, se volesse sovrascrivere le impostazioni JWT, potrebbe avere un file appsettings.json come questo.

{
  "Jwt": {  
    "SigningKey": "PleaseUseYourOwnSigningKeyHere",  
    "Issuer": "IronmanSoftware",
    "Audience": "PowerShellUniversal"
  }
}

Variabili di ambiente

Può anche impostare variabili di ambiente per le sue impostazioni. Le variabili di ambiente devono avere un trattino basso tra ogni sottoinsieme del file appsettings.json. Ad esempio, se desidera modificare la chiave di firma JWT tramite variabile di ambiente, imposterebbe la variabile $Env:Jwt__SigningKey. Se volesse impostare l'URL dell'API esterna, imposterebbe $Env:Api__Url.

Esempi

Utilizzo di una variabile di ambiente per il segreto OpenID Connect.

$Env:Authentication__OIDC__ClientSecret = "mySecret"

Utilizzo di una variabile di ambiente per la chiave di firma JWT.

$Env:Jwt__SigningKey = "mySigningKey"

Riga di comando

Può specificare la posizione del file appsettings.json utilizzando l'argomento della riga di comando --appsettings per Universal.Server.exe .

.\Universal.Server.exe --appsettings C:\appsettings.json

Descrizioni delle impostazioni

Kestrel / Endpoint

Valore predefinito

"Kestrel": {
  "Endpoints": {
    "HTTP": {
      "Url": "http://*:5000"
    }
  },
  "RedirectToHttps": "false"
},

La sezione degli endpoint Kestrel le consente di configurare il server web. Queste impostazioni non vengono utilizzate quando l'hosting avviene in IIS. In questa sezione può configurare opzioni come HTTPS e la porta su cui PowerShell Universal resterà in ascolto.

Kestrel è l'implementazione del server web per ASP.NET Core utilizzata da PowerShell Universal. Per maggiori informazioni sulle opzioni di configurazione di Kestrel, visiti questa pagina della documentazione Microsoft.

Chiave	Descrizione
RedirectToHttps	Se impostato su true, il server web reindirizzerà le richieste HTTP a HTTPS
BasePath	Richiesto quando si configura PowerShell Universal come sito annidato all'interno di IIS. Deve contenere il percorso IIS annidato, ad esempio /psu
Hsts \ MaxAgeDays	Imposta l'età massima in giorni per HTTP Strict Transport Security.
CookiePolicy	Se impostato su SameSiteNone, il valore SameSite=None verrà impostato sui cookie in PSU. Questo è utile quando si ospita PSU in iframe.
Headers	Un oggetto in cui le chiavi sono le intestazioni da impostare su ogni richiesta e il valore è il valore dell'intestazione.

Azure Application Insights

Valore predefinito

"ApplicationInsights": {
  "ConnectionString": ""
},

Chiave	Descrizione
ConnectionString	Imposta la stringa di connessione per Application Insights.

Registrazione

Valore predefinito

{
    "SystemLogPath": "%PROGRAMDATA%/PowerShellUniversal/Logs/System/log.txt",
    "SystemLogLevel": "Information"
}

Imposta il percorso e il livello del log di sistema. Questo verrà sovrascritto dal livello di log in settings.ps1 dopo il suo caricamento. Questa impostazione è utile per il debug dei problemi durante l'avvio del sistema.

Chiave	Descrizione
SystemLogPath	Percorso del file di log.
SystemLogLevel	Il livello del log di sistema. Può impostare valori come Debug, Information, Warning ed Error.

AllowedHosts

Valore predefinito

    "AllowedHosts": "*",

Gli host a cui è consentito connettersi al server web. Il valore predefinito è qualsiasi host.

CorsHosts

Valore predefinito

    "CorsHosts": "",

Configura gli host a cui è consentito effettuare richieste di condivisione delle risorse tra origini diverse (CORS) al server. Per consentire più host, separi ogni host con un punto e virgola.

"CorsHosts" : "https://www.google.com;https://login.microsoftonline.com"

Data

Valore predefinito

"Data": {
  "RepositoryPath": "%ProgramData%\\UniversalAutomation\\Repository",
  "ConnectionString": "%ProgramData%\\UniversalAutomation\\database.db",
  "GitRemote": "",
  "GitUserName": "",
  "GitPassword": "", 
  "GitBranch": "",
  "ConfigurationScript": "",
  "ExternalGitClient": false,
  "Mode": "automatic",
  "SlowQueryLimit": 500,
  "Persistence": {}
},

Chiave	Descrizione
RepositoryPath	Percorso della posizione di archiviazione dei file di configurazione utilizzati da Universal.
ConnectionString	Percorso del database utilizzato da Universal.
GitRemote	Remote Git utilizzato per la sincronizzazione con Universal.
GitBranch	Branch Git di cui effettuare il checkout durante la sincronizzazione con Universal.
GitUserName	Nome utente Git utilizzato per la sincronizzazione con GitRemote. Quando si utilizza un PAT, può essere un valore qualsiasi.
GitPassword	La password utente Git o il token di accesso personale utilizzato per la sincronizzazione con GitRemote.
GitSyncTimeout	Il numero di secondi prima che un comando del client git esterno vada in timeout. Il valore predefinito è 60 secondi.
ConfigurationScript	Posizione di uno script di configurazione personalizzato da caricare. Da questo script può restituire oggetti come script, dashboard ed endpoint.
ExternalGitClient	Se impostato su true, verrà utilizzato il client Git del sistema operativo anziché il client della libreria integrata
Mode	Imposta la modalità git. Può essere manuale o automatica. Il valore predefinito è manuale.
SlowQueryLimit	Il numero di millisecondi di esecuzione di una query SQL prima che venga scritto un messaggio di log. Il valore predefinito è 200 ms. Disponibile solo per MS SQL.
Persistence	Configura la persistenza delle risorse nel database.
InvisibilityTimeoutMinutes	Il numero di minuti prima che un job vada in timeout in Hangfire. Il valore predefinito è 5. Si applica solo a PostgreSQL.

API

Valore predefinito

"Api": {
  "Url": "",
  "HideManagementDoc": false
},

Chiave	Descrizione
Url	Imposta l'URL esterno utilizzato internamente da Universal. Questo è necessario quando si esegue Universal all'interno di un proxy inverso come IIS. Quando si utilizzano cmdlet come Get-UAScript all'interno di un job in esecuzione, il server Universal deve determinare dove si trova il server web. Quando è in esecuzione all'interno di un proxy, non può determinarlo da solo. In questa configurazione dovrà impostare questo valore in modo che punti al nome e alla porta del sito web IIS.
HideManagementDoc	Se true, nasconde la documentazione OpenAPI dell'API di gestione di PowerShell Universal.

`Api.Url` viene utilizzato internamente da PowerShell Universal quando i cmdlet devono richiamare il server PSU da job, endpoint o altri contesti di esecuzione interni. Negli ambienti con proxy inverso o bilanciamento del carico, si assicuri che questo valore punti a un URL stabile e direttamente raggiungibile per l'host PSU. L'utilizzo di un alias DNS o di un altro endpoint indiretto può causare errori intermittenti dei cmdlet se tale alias viene risolto attraverso un proxy o un percorso di backend instabile. Se necessario, specifichi esplicitamente `-ComputerName` per la chiamata del cmdlet.

Autenticazione

Valore predefinito

"Authentication" : {
    "Windows": {
      "Enabled": "false"
    },
    "WSFed": {
      "Enabled": "false",
      "MetadataAddress": "",
      "Wtrealm": "",
      "CallbackPath": "/auth/signin-wsfed",
      "Wreply": "",
      "UseTokenLifetime": true,
      "CorrelationCookieSameSite": ""
    },
    "OIDC": {
      "Enabled": "false",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "",
      "ClientSecret": "",
      "Resource": "",
      "Authority": "",
      "ResponseType": "",
      "SaveTokens": "false",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true
    },
    "OIDC": {
      "Enabled": "false",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "",
      "ClientSecret": "",
      "Resource": "",
      "Authority": "",
      "ResponseType": "",
      "SaveTokens": "false",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true,
      "Scope": "openid profile groups",
      "GetUserInfo": false
    },
    "ClientCertificate": {
      "Enabled": "false"
    },
    "SessionTimeout": "25"
  },

Windows

Chiave	Descrizione
Enabled	Abilita o disabilita l'autenticazione di Windows.

OIDC

Impostazioni di autenticazione OpenID Connect.

Chiave	Descrizione
Enabled	Indica se OIDC è abilitato.
CallbackPath	Il percorso a cui il provider OIDC effettuerà la richiamata.
ClientID	L'ID client OIDC configurato.
ClientSecret	Il segreto client OIDC configurato.
Resource	Risorse concesse con questo token OIDC.
Authority	L'autorità da richiamare durante l'autenticazione. Si tratta dell'URL del suo provider OIDC.
ResponseType	Il tipo di risposta restituito dal provider. Il valore più comune qui è code
SaveTokens	Indica se salvare il token in modo che sia disponibile per endpoint come le dashboard.
CorrelationCookieSameSite	Impostazioni SameSite del cookie di correlazione.
UseTokenLifetime	Se impostato su true, la durata del cookie verrà impostata sulla durata del token. Questo sovrascrive il valore di timeout della sessione.
GetUserInfo	Restituisce informazioni aggiuntive sull'utente da utilizzare nei file roles.ps1. È possibile accedere alle informazioni aggiuntive tramite la variabile $UserInfo.

WSFed

Impostazioni di autenticazione WS-Federation.

Chiave	Descrizione
Enabled	Indica se WS-Fed è abilitato.
MetadataAddress	L'indirizzo dei metadati da cui recuperare le informazioni sull'istanza WS-Fed.
Wrealm
Wreply
CallbackPath	Il percorso a cui il provider OIDC effettuerà la richiamata.
UseTokenLifetime	Se impostato su true, la durata del cookie verrà impostata sulla durata del token. Questo sovrascrive il valore di timeout della sessione.
CorrelationCookieSameSite	Impostazioni same site del cookie di correlazione.

Soglia di timeout della sessione (minuti)

Chiave	Descrizione
SessionTimeout	Numero di minuti prima che una sessione con accesso effettuato vada in timeout (valore predefinito 25)

JWT

Impostazioni di configurazione dei JSON Web Token

Valore predefinito

"Jwt": {  
  "SigningKey": "PleaseUseYourOwnSigningKeyHere",  
  "Issuer": "IronmanSoftware",
  "Audience": "PowerShellUniversal"
},

Chiave	Descrizione
SigningKey	La chiave di firma per i token JWT.
Issuer	L'emittente che verrà incluso nel token.
Audience	Il destinatario che verrà incluso nel token.

Secrets

Opzioni per configurare le casseforti dei segreti predefinite.

Valore predefinito

"Secrets": {
  "SecretStore": {
    "Password": "PSUSecretStore"
  },
  "Database": {
    "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf",
    "Password": "",
    "KeySize": 128
  },
  "SecretManagement": {
    "OutOfProcess": false
  }
}

Chiave	Descrizione
SecretStore \ Password	La password per la cassaforte PSUSecretStore. Utilizza il modulo Microsoft SecretStore.
Database \ EncryptionKey	La chiave di crittografia AES 128 utilizzata per crittografare i segreti archiviati nel database.
Database \ Password	Una password utilizzata per generare una chiave di crittografia. EncryptionKey verrà ignorata se viene specificata una password.
Database \ KeySize	Il numero di byte della chiave. Deve essere un multiplo di 128 e il valore predefinito è 128.
SecretManagement \ OutOfProcess	Indica se le operazioni di gestione dei segreti devono essere eseguite fuori processo. Il valore predefinito è false.

Generazione di una chiave di crittografia

Le chiavi di crittografia sono a 128 bit e richiedono la lunghezza corretta. Sono codificate come stringa base64 e convertite in byte all'avvio.

È possibile utilizzare il codice seguente per generare una chiave segreta della lunghezza corretta.

$random = [System.Security.Cryptography.RandomNumberGenerator]::Create();
$buffer = New-Object byte[] 16;
$random.GetBytes($buffer);
[Convert]::ToBase64String($buffer)

UniversalAutomation

Impostazioni per le funzionalità specifiche dell'automazione.

Valore predefinito

"UniversalAutomation": {
    "Queues": [],
    "JobHandshakeTimeout": 30,
    "JobDebugging": false,
    "ContinueJobOnServerStop": false,
    "HangfireWorkerCount" : 100
  }

Chiave	Descrizione
Queues	Code personalizzate di cui questa istanza PSU fa parte.
JobHandshakeTimeout	Il numero di secondi di attesa prima di far fallire un processo dopo l'avvio del processo PowerShell che lo esegue, se il processo non comunica con il server.
JobDebugging	Indica se generare file nella directory temporanea all'avvio del processo. Utile per il debug se i processi vanno in timeout prima di avviarsi.
ContinueJobOnServerStop	Indica se continuare l'esecuzione di un processo dopo l'arresto del servizio. L'avanzamento del processo non verrà segnalato, ma lo script continuerà a essere eseguito.
HangfireWorkerCount	Il numero di thread worker Hangfire da avviare sul server. Questa impostazione è specifica del nodo. Il valore predefinito è 100. Corrisponde al numero totale di processi che possono essere eseguiti contemporaneamente su un determinato nodo.

HideAdminConsole

{
    "HideAdminConsole": false
}

Impedisce al servizio di erogare la console di amministrazione. In questo modo la console di amministrazione non potrà essere utilizzata da alcun utente, inclusi gli amministratori.

NodeName

{
    "NodeName": ""
}

L'opzione del nome del nodo viene utilizzata per modificare il nome dell'istanza di PowerShell Universal. Per impostazione predefinita, corrisponde al nome del computer locale. Quando si utilizza PowerShell Universal in un container, ciò può risultare problematico perché il nome può cambiare ogni volta che il container viene riavviato.

Per impostare un nome di nodo statico, modificare questo parametro.

Risorse statiche

È possibile definire risorse statiche utilizzando le impostazioni dell'applicazione. Queste includono le variabili di ambiente e appsettings.json. Per definire una risorsa, utilizzare il nodo Resources all'interno di appsettings.json oppure il prefisso Resources con una variabile di ambiente.

Ad esempio, per definire un ruolo statico in appsettings.json, utilizzare quanto segue.

{
    "Resources": {
        "Roles": [
            {
                "Name": "Static Role",
                "ClaimType": "group",
                "ClaimValue": "xyz123"
            }
        }
    }
}

È possibile definire lo stesso ruolo utilizzando le variabili di ambiente.

$ENV:Resources__Roles__0__Name = "Static Role"
$ENV:Resources__Roles__0__ClaimType = "group"
$ENV:Resources__Roles__0__ClaimValue = "xyz123"

Esempio: Docker Compose

È possibile utilizzare le variabili di ambiente in un file YML di Docker Compose per definire risorse che saranno disponibili in PowerShell Universal dopo l'avvio. L'esempio seguente crea tag e un ruolo, imposta un titolo di amministrazione personalizzato, aggiunge una licenza e imposta l'ambiente predefinito.

services:    
    psu:         
      image: ironmansoftware/universal:latest
      environment:
          - Resources__Tags__0__Name=Production  
          - Resources__Tags__1__Name=Development
          - Resources__Roles__0__Name=PSUAdmin
          - Resources__Roles__0__ClaimType=groups
          - Resources__Roles__0__ClaimValue=1234567890abcdef1234567890abcdef
          - Resources__Roles__0__Permissions_0=*
          - Resources__Settings__DefaultEnvironment=PowerShell 7
          - Resources__Branding__AdminConsoleTitle=PSU Admin Console
          - Authentication__OIDC__Enabled=true
          - Authentication__OIDC__ClientId=123-123-123-123-123
          - Authentication__OIDC__ClientSecret=secret
          - Authentication__OIDC__Authority=https://login.microsoftonline.com/123-123-123-123
          - PSULICENSE=<License></License>
      ports:
        - "5000:5000"

Impostazioni del runtime .NET

Anche il runtime .NET supporta impostazioni che si applicano a PowerShell Universal. Potrebbe essere necessario modificare queste impostazioni in base alle proprie esigenze.

Tutte le informazioni sono disponibili nelle impostazioni del runtime .NET su Microsoft Docs.

File temporanei eccessivi

Negli ambienti Linux, il runtime potrebbe creare molti file temporanei per abilitare le funzionalità di debug. Disabilitando le impostazioni di diagnostica del runtime si eviterà che ciò accada. Con questa opzione disabilitata non sarà possibile utilizzare gli strumenti di debug .NET.

$Env:DOTNET_EnableDiagnostics = $false

Vedere anche

• Devolutions Academy – Creating a basic endpoint