> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/it/config/settings.md). # 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 è possibile applicare a PowerShell Universal. Sebbene sia possibile modificare direttamente questo file, si consiglia di utilizzare uno dei seguenti metodi per rendere persistenti le impostazioni, poiché il file `appsettings.json` nella directory di installazione verrà sovrascritto durante gli aggiornamenti. {% hint style="info" %} Quando è installato dall'MSI, la directory di installazione di PowerShell Universal è `${env:ProgramFiles(x86)}\Universal`. {% endhint %} ## ProgramData AppSettings.json È possibile creare un file appsettings.json all'interno della cartella `$Env:ProgramData\PowerShellUniversal`. È possibile utilizzare un sottoinsieme delle impostazioni presenti nel file `appsettings.json`. Ad esempio, se si desidera sovrascrivere le impostazioni JWT, si potrebbe avere un file `appsettings.json` come questo. ```javascript { "Jwt": { "SigningKey": "PleaseUseYourOwnSigningKeyHere", "Issuer": "IronmanSoftware", "Audience": "PowerShellUniversal" } } ``` ## Variabili d'ambiente È inoltre possibile impostare variabili d'ambiente per le proprie impostazioni. Le variabili d'ambiente devono avere un trattino basso tra ogni sottoinsieme del file `appsettings.json`. Ad esempio, se si desidera modificare la chiave di firma JWT tramite una variabile d'ambiente, si imposterà la variabile `$Env:Jwt__SigningKey`. Se si desidera impostare l'URL dell'API esterna, si imposterà `$Env:Api__Url`. ### Esempi Utilizzo di una variabile d'ambiente per il segreto OpenID Connect. ``` $Env:Authentication__OIDC__ClientSecret = "mySecret" ``` Utilizzo di una variabile d'ambiente per la chiave di firma JWT. ``` $Env:Jwt__SigningKey = "mySigningKey" ``` ## Riga di comando È possibile specificare la posizione del file `appsettings.json` utilizzando l'argomento della riga di comando `--appsettings` per `Universal.Server.exe` . ```powershell .\Universal.Server.exe --appsettings C:\appsettings.json ``` ## Descrizioni delle impostazioni ### Kestrel / Endpoints **Valore predefinito** ```javascript "Kestrel": { "Endpoints": { "HTTP": { "Url": "http://*:5000" } }, "RedirectToHttps": "false" }, ``` La sezione degli endpoint Kestrel consente di configurare il server web. Queste impostazioni non vengono utilizzate quando si ospita in IIS. In questa sezione è possibile configurare opzioni come HTTPS e la porta su cui PowerShell Universal sarà 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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?view=aspnetcore-3.1#listenoptionsusehttps). | Chiave | Descrizione | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | RedirectToHttps | Se impostato su true, il server web reindirizzerà le richieste HTTP a HTTPS | | BasePath | Obbligatorio 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](https://https.cio.gov/hsts/). | | CookiePolicy | Se impostato su SameSiteNone, il valore SameSite=None verrà impostato sui cookie in PSU. Ciò è 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** ```javascript "ApplicationInsights": { "ConnectionString": "" }, ``` | Chiave | Descrizione | | ---------------- | ----------------------------------------------------------- | | ConnectionString | Imposta la stringa di connessione per Application Insights. | ### Logging **Valore predefinito** ```javascript { "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. È possibile impostare valori come Debug, Information, Warning ed Error. | ### AllowedHosts **Valore predefinito** ```javascript "AllowedHosts": "*", ``` Gli host a cui è consentito connettersi al server web. Il valore predefinito è qualsiasi host. ### **CorsHosts** **Valore predefinito** ```javascript "CorsHosts": "", ``` Configura gli host a cui è consentito effettuare richieste di condivisione delle risorse tra origini (CORS) al server. Per consentire più host, separi ogni host con un punto e virgola. ```javascript "CorsHosts" : "https://www.google.com;https://login.microsoftonline.com" ``` ### **Data** **Valore predefinito** ```javascript "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 | Ramo Git da estrarre 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 è possibile restituire oggetti come script, dashboard ed endpoint. | | ExternalGitClient | Se impostato su true, verrà utilizzato il client Git del sistema operativo invece del client della libreria integrata | | Mode | Imposta la modalità git. Può essere manuale o automatica. Il valore predefinito è manuale. | | SlowQueryLimit | Il numero di millisecondi per cui una query SQL deve essere eseguita 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](/powershell-universal/it/config/repository.md). | | InvisibilityTimeoutMinutes | Il numero di minuti prima che un processo vada in timeout in Hangfire. Il valore predefinito è 5. Si applica solo a PostgreSQL. | ### **API** **Valore predefinito** ```javascript "Api": { "Url": "", "HideManagementDoc": false }, ``` | Chiave | Descrizione | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Url | Imposta l'URL esterno utilizzato internamente da Universal. Ciò è necessario quando si esegue Universal all'interno di un proxy inverso come IIS. Quando si utilizzano cmdlet come `Get-UAScript` all'interno di un processo 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. Sarà opportuno configurare questo valore in modo che punti al nome e alla porta del sito web IIS in questa configurazione. | | HideManagementDoc | Se true, nasconde la documentazione OpenAPI dell'API di gestione di PowerShell Universal. | {% hint style="warning" %} \`Api.Url\` viene utilizzato internamente da PowerShell Universal quando i cmdlet devono richiamare il server PSU da processi, endpoint o altri contesti di esecuzione interni. In 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. {% endhint %} ### **Authentication** **Valore predefinito** ```javascript "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](/powershell-universal/it/api/security.md#authenticating-with-windows-authentication). | #### 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 provider OIDC. | | ResponseType | Il tipo di risposta restituita dal provider. Il valore più comune è `code` | | SaveTokens | Indica se salvare il token in modo che sia disponibile per endpoint come le dashboard. | | CorrelationCookieSameSite | [Impostazioni SameSite del cookie di correlazione.](https://docs.microsoft.com/en-us/aspnet/core/security/samesite?view=aspnetcore-5.0) | | UseTokenLifetime | Se impostato su true, la durata del cookie sarà impostata sulla durata del token. Questo sovrascrive il valore di timeout della sessione. | | GetUserInfo | Restituisce informazioni aggiuntive sull'utente da utilizzare all'interno dei 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 eseguirà la callback. | | UseTokenLifetime | Se impostato su true, la durata del cookie sarà impostata sulla durata del token. Questo sovrascrive il valore di timeout della sessione. | | CorrelationCookieSameSite | [Impostazioni same site del cookie di correlazione.](https://docs.microsoft.com/en-us/aspnet/core/security/samesite?view=aspnetcore-5.0) | #### Soglia di timeout della sessione (minuti) | Chiave | Descrizione | | -------------- | --------------------------------------------------------------------------------------------- | | SessionTimeout | Numero di minuti prima che una sessione connessa vada in timeout (il valore predefinito è 25) | ### **JWT** Impostazioni di configurazione di JSON Web Token **Valore predefinito** ```javascript "Jwt": { "SigningKey": "PleaseUseYourOwnSigningKeyHere", "Issuer": "IronmanSoftware", "Audience": "PowerShellUniversal" }, ``` | Chiave | Descrizione | | ---------- | ------------------------------------------- | | SigningKey | La chiave di firma per i token JWT. | | Issuer | L'emittente che sarà incluso nel token. | | Audience | Il destinatario che sarà incluso nel token. | ### Secrets Opzioni per configurare le casseforti dei segreti predefinite. **Valore predefinito** ```json "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. ```powershell $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** ```json "UniversalAutomation": { "Queues": [], "JobHandshakeTimeout": 30, "JobDebugging": false, "ContinueJobOnServerStop": false, "HangfireWorkerCount" : 100 } ``` | Chiave | Descrizione | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Queues | Code personalizzate di cui fa parte questa istanza di PSU. | | JobHandshakeTimeout | Il numero di secondi di attesa prima di far fallire un job dopo l'avvio del processo PowerShell che deve eseguirlo, se il processo non comunica con il server. | | JobDebugging | Indica se generare file nella directory temporanea all'avvio di un job. Questo è utile per il debug se i job vanno in timeout prima dell'avvio. | | ContinueJobOnServerStop | Indica se continuare l'esecuzione di un job dopo l'arresto del servizio. L'avanzamento del job non potrà essere 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 job che possono essere eseguiti contemporaneamente su un determinato nodo. | ### **HideAdminConsole** ```json { "HideAdminConsole": false } ``` Impedisce al servizio di erogare la console di amministrazione. Questo impedirà l'utilizzo della console di amministrazione da parte di qualsiasi utente, inclusi gli amministratori. ### NodeName ```json { "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, questo può diventare 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'app. 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. ```json { "Resources": { "Roles": [ { "Name": "Static Role", "ClaimType": "group", "ClaimValue": "xyz123" } } } } ``` È possibile definire lo stesso ruolo utilizzando le variabili di ambiente. ```powershell $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 le 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. ```yaml 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= ports: - "5000:5000" ``` ## Impostazioni del runtime .NET Il runtime .NET supporta anche impostazioni che si applicano a PowerShell Universal. Potrebbe essere necessario modificare queste impostazioni in base alle proprie esigenze. È possibile trovare tutte le informazioni sulle [impostazioni del runtime .NET nella documentazione Microsoft](https://learn.microsoft.com/en-us/dotnet/core/runtime-config/). ### File temporanei eccessivi Negli ambienti Linux, il runtime potrebbe creare molti file temporanei per abilitare le funzionalità di debug. [Disabilitando le impostazioni di diagnostica](https://learn.microsoft.com/en-us/dotnet/core/runtime-config/debugging-profiling#enable-diagnostics) del runtime si impedirà che ciò avvenga. Con questa opzione disabilitata non sarà possibile utilizzare gli strumenti di debug .NET. ```powershell $Env:DOTNET_EnableDiagnostics = $false ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/it/config/settings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.