Installazione e configurazione del server di log
Il server di log può essere configurato su singoli server Linux o Windows oppure ospitato sull’appliance connettore Citrix e sfruttare gli aggiornamenti evergreen. Fare riferimento alla sezione pertinente per i passaggi di installazione e configurazione per ciascuna opzione.
Nota per l’installazione
Per una maggiore sicurezza, si consiglia di utilizzare HTTPS nella distribuzione.
Assicurarsi che la porta selezionata non sia già in uso.
Evitare di utilizzare porte privilegiate (0–1023) in quanto richiedono autorizzazioni a livello di amministratore o di sistema.
Verificare che le regole del firewall consentano il traffico sulla porta scelta.
Utilizzare un numero di porta all’interno dell’intervallo valido (0–65535), ma evitare le porte comunemente utilizzate dai servizi di sistema per prevenire conflitti.
Se si utilizza l’appliance connettore Citrix per distribuire il server di log, assicurarsi che sia configurata solo la porta 443.
I numeri di porta utilizzati negli esempi (8080 per HTTP e 8443 per HTTPS) sono solo a scopo di riferimento. Non è necessario utilizzare queste porte esatte. Selezionare i numeri di porta appropriati in base al proprio ambiente e seguire le linee guida di installazione sopra descritte durante la configurazione del server di log AOT.
Installazione del server di log tramite l’appliance connettore Citrix
Il server di log può essere distribuito all’interno dell’appliance connettore Citrix. Questo approccio elimina la necessità di distribuire e gestire una VM host e di scaricare manualmente immagini o eseguire comandi container. Il server di log viene automaticamente integrato durante l’aggiornamento dell’appliance connettore e rimane aggiornato tramite gli aggiornamenti continui del connettore, garantendo di avere sempre la versione più recente. Per maggiori informazioni, vedere Aggiornamenti dell’appliance connettore
Passaggi per distribuire il server di log tramite l’appliance connettore Citrix
-
Se il tuo ambiente non dispone già di un’appliance connettore, distribuiscila sul tuo hypervisor o dal tuo marketplace di cloud pubblico. L’appliance connettore Citrix minima richiesta è la 11.4.1.444. Dopo l’importazione, registra l’appliance con Citrix Cloud. Per maggiori informazioni, vedere Ottenere l’appliance connettore
-
Per impostazione predefinita, l’appliance connettore dispone di 2 vCPU e 4 GB di memoria; aumentare le risorse ad almeno 4 vCPU e 16 GB di memoria per gestire le richieste del server di log.
-
Cloud Monitor recupera i log AOT tramite il servizio Monitor Connector in esecuzione su un Cloud Connector Windows supportato nella Resource Location. Se il Log Server è distribuito sull’appliance Citrix Connector, un Cloud Connector Windows supportato deve essere presente anche nella stessa Resource Location. La sola Connector Appliance non è sufficiente per consentire a Cloud Monitor di recuperare le tracce AOT. Il Cloud Connector deve eseguire la versione 6.141.0.13739 (o 4.420.0.13739) o successiva. Le versioni precedenti causeranno l’errore della chiamata API
GetAotTraces, con conseguente errore HTTP 500 in Monitor. -
L’appliance Connector fornisce un certificato autofirmato che viene servito a un browser che si connette alla pagina di amministrazione dell’appliance Connector. Per potersi connettere al logserver tramite HTTPS, è possibile sostituire questo certificato autofirmato con uno proprio firmato dalla propria organizzazione o generato utilizzando la catena di fiducia della propria organizzazione; per maggiori dettagli, fare riferimento a Gestione dei certificati o Sostituzione del certificato del server.
-
Una volta completato l’aggiornamento, accedere all’interfaccia utente dell’appliance Connector all’indirizzo
https://<connector-appliance-FQDN-or-IP>/?enable=logserver, assicurandosi di avere “?enable=logserver” per poter visualizzare l’interfaccia utente del logserver. La nuova scheda Log Server mostra ora le opzioni di gestione dell’archiviazione e delle chiavi di autenticazione.
-
Il disco di avvio dell’appliance Connector ha una capacità di 20 GB. Per supportare l’archiviazione efficiente dei log sul logserver, è necessario aggiungere un altro disco virtuale all’appliance Connector utilizzando l’hypervisor o la piattaforma di gestione cloud. Questo disco aggiuntivo dovrebbe avere spazio sufficiente per soddisfare le esigenze di archiviazione dei log (come spiegato nella sezione precedente). Lo screenshot di XenServer di seguito mostra un esempio di appliance Connector con un disco aggiuntivo configurato.
Nota:
Un requisito noto per VMware ESXi: gli utenti devono collegare il disco dati aggiuntivo a un controller SCSI diverso da quello utilizzato dal disco root.
-
Dopo aver aggiunto il disco chiave, l’interfaccia utente del logserver lo rileverà automaticamente, consentendo di formattarlo e montarlo nel container del logserver sull’appliance Connector.
-
Una volta cliccato il pulsante “Collega disco”, il disco verrà montato nel container del logserver.
-
La pagina principale visualizzerà la dimensione del disco insieme alle informazioni su quanto spazio è utilizzato e quanto ne rimane.
-
Dopo aver collegato il disco, verificare che il Log Server sia in esecuzione chiamando l’endpoint ping:
https://<connector-appliance-FQDN>/ctxlogserver/Ping. Una risposta pong conferma che il Log Server è stato avviato correttamente. -
Fai clic su “Genera chiave”, inserisci il nome del ruolo, quindi copia o scarica la chiave di autenticazione. La chiave non verrà più mostrata dopo aver chiuso la finestra.
Installazione Linux
- Scarica l’immagine del container Docker del server di log da download Citrix.
- Posiziona i file scaricati nella stessa directory.
- Esegui il programma di installazione nella directory con il terminale (Linux) o il prompt dei comandi (Windows) e segui le istruzioni:
chmod +x ./InstallLogServer
#Install with https mode with port 8443 with default path
./InstallLogServer --https --cert </path/your_private_cert_key.pfx> --port 8443
#Install with http mode, with port 8080 with default path
./InstallLogServer --port 8080
#Command to change the config path and data path of your choice with https mode
./InstallLogServer --https --cert </path/your_private_cert_key.pfx> --port 8443 --config /Path/LogServer/Config --database /Path/LogServer/Data
#Command to change the config path and data path of your choice with http mode
./InstallLogServer --port 8080 --config /Path/LogServer/Config --database /Path/LogServer/Data
#To support CWA client uploading AOT logs, some additional parameters need to be added after the install log server command.
--sta-server http://STA_SERVER_FQDN:port --log-server LOG_SERVER_FQDN:PORT
<!--NeedCopy-->
Dove,
-
STA_SERVER_FQDN è il nome host o l’indirizzo IP del server STA (nelle installazioni on-premise, il server STA viene solitamente installato insieme al DDC).
-
LOG_SERVER_FQDN e PORT sono il nome host del server di log stesso e la porta specificata (8080, 8443 o il valore –port nel parametro di installazione).
-
Il certificato del server di log your_private_cert_key.pfx deve essere considerato attendibile da altri componenti Citrix, dove il client AOT utilizzerà la connessione TLS per caricare i log.
L’indirizzo STA_SERVER consente al server di log di emettere ticket STA di riconnessione ai client di Citrix Workspace app (CWA) quando StoreFront non può fornirli, ad esempio dopo un timeout di sessione. Ciò consente ai client CWA di ristabilire la connessione direttamente con il server di log in caso di interruzione della connessione.
L’indirizzo LOG_SERVER viene utilizzato quando il server di log richiede un ticket STA dal server STA configurato. Il server STA restituisce un ticket che autorizza le connessioni specificamente all’endpoint del server di log.
Questi parametri sono facoltativi se i client CWA non necessitano di ticket STA di riconnessione o si connettono direttamente a LogServer senza un gateway.
Post-installazione su Linux
Dopo l’installazione, vengono generati alcuni utili file di script:
# In Linux, sh scripts will be generated
DownloadLogsByTime.sh
DownloadLogsByWords.sh
GetAuthKey.sh
ListMachines.sh
StartLogServer.sh
<!--NeedCopy-->
Utilizzare ./StartLogServer.sh to start the server. Check your configpath/weblogs.txt per confermare che LogServer è stato avviato correttamente.
Se LogServer si avvia correttamente, è possibile visualizzare il messaggio seguente nel file weblogs. La porta 5000 viene utilizzata da LogServer internamente nei container Docker con il protocollo http o https selezionato.
Now listening on https://[::]:5000
<!--NeedCopy-->
Se il server di log è stato installato in modalità HTTP, i log di successo dovrebbero mostrare quanto segue:
Now listening on http://[::]:5000
<!--NeedCopy-->
Se LogServer utilizza HTTPS, assicurarsi che il suo certificato sia attendibile su tutte le macchine che caricano i log AOT
Nota:
La porta configurata nella fase di installazione (8080 o 8443 o qualsiasi porta specificata) deve essere utilizzata durante la configurazione dell’URL di LogServer in DDC, Storefront, VDA, ecc.
Di solito, l’avvio su Linux richiede da 30 a 60 secondi.
Installazione di Windows
- Scaricare l’immagine del container Docker del server di log da download Citrix.
- Posizionare i file scaricati nella stessa directory.
- Eseguire il programma di installazione nella directory con il terminale (Linux) o il prompt dei comandi (Windows) e seguire le istruzioni:
Fase 1
Installare Docker Desktop (potrebbe essere necessario un abbonamento) per Windows sulla VM del server di log. Seguire i passaggi seguenti per assicurarsi che Docker Desktop si installi e si avvii correttamente sui sistemi Windows che si basano su WSL 2.
-
Impostare il limite di memoria >= 12 GB nelle impostazioni di Docker Desktop
-
Docker Desktop richiede le seguenti funzionalità di Windows, assicurarsi che queste funzionalità siano abilitate.
- Hyper-V
- Piattaforma macchina virtuale
- Sottosistema Windows per Linux (WSL)
-
Se mancano delle funzionalità, installarle e riavviare la VM affinché abbiano effetto.
-
Dopo il riavvio del sistema, aprire PowerShell (Esegui come amministratore) e aggiornare WSL eseguendo il comando
wsl --update -
Docker Desktop richiede WSL 2. Configuralo come predefinito eseguendo il comando
wsl --set-default-version 2 -
Una volta che WSL è aggiornato e le funzionalità di Windows richieste sono abilitate, il motore di Docker Desktop dovrebbe avviarsi correttamente.
Passaggio 2
Eseguire i comandi seguenti per continuare l’installazione.
Nota:
La posizione predefinita delle cartelle Config e Database (Dati) viene creata in C:\Users<username>\LogServer. È possibile modificarle con i comandi seguenti
#Install with https mode with port 8443 with default path
InstallLogServer.exe --https --cert <c:\path\cert.pfx> --port 8443
#Install with http mode, with port 8080 with default path
InstallLogServer.exe --port 8080
#Command to change the config path and data path of your choice with https mode
InstallLogServer.exe --https --cert <c:\path\cert.pfx> --port 8443 --config C:\LogServer\Config --database C:\LogServer\Datacmd
#Install with specific config path and data path
InstallLogServer.exe --port 8080 --config C:\LogServer\Config --database C:\LogServer\Datacmd
#To support CWA client uploading AOT logs, some additional parameters need to be added after the install log server command.
--sta-server http://STA_SERVER_FQDN:port --log-server LOG_SERVER_FQDN:PORT
<!--NeedCopy-->
Dove,
-
STA_SERVER_FQDN è il nome host o l’indirizzo IP del server STA (nelle installazioni on-premise, il server STA di solito si installa insieme a DDC).
-
LOG_SERVER_FQDN e PORT sono il nome host del server di log stesso e la porta specificata (8080, 8443 o il valore –port nel parametro di installazione).
-
Il certificato del server di log your_private_cert_key.pfx deve essere considerato attendibile dagli altri componenti Citrix, dove il client AOT utilizzerà la connessione TLS per caricare i log.
L’indirizzo STA_SERVER consente a LogServer di fornire ticket STA di riconnessione ai client CWA quando StoreFront non può fornirli a causa del timeout della sessione. Di conseguenza, i client CWA possono ottenere i ticket di riconnessione direttamente da LogServer in caso di errori di connessione.
L’indirizzo LOG_SERVER viene utilizzato quando il server di log richiede un ticket STA dal STA_SERVER. Il STA_SERVER rilascia un ticket STA che autorizza esclusivamente le connessioni all’indirizzo LOG_SERVER.
Questi parametri sono facoltativi se i client CWA non necessitano di ticket STA di riconnessione o si connettono direttamente a LogServer senza un gateway.
Post-installazione su Windows
Dopo l’installazione, alcuni utili file di script vengono generati nella stessa directory in cui sono stati salvati i file del programma di installazione.
Nota:
È possibile spostare questi file in una posizione diversa. Tuttavia, ricordarsi la nuova posizione, poiché saranno nuovamente necessari durante la configurazione del server di log.
#In Windows, bat scripts will be generated in the same directory where you saved the installer files.
DownloadLogsByTime.bat
DownloadLogsByWords.bat
GetAuthKey.bat
ListMachines.bat
StartLogServer.bat
<!--NeedCopy-->
Utilizzare StartLogServer.bat per avviare il server di log.
Controllare il configpath\weblogs.txt per confermare che LogServer sia stato avviato correttamente
Quando i log mostrano quanto segue, significa che il server di log è stato avviato correttamente. Se LogServer si avvia correttamente, verrà visualizzato il messaggio seguente nel file weblogs. La porta 5000 viene utilizzata da LogServer internamente nei container Docker con protocollo http o https selezionato.
Now listening on: https://[::]:5000
<!--NeedCopy-->
Se il server di log è stato installato in modalità HTTP, i log di successo dovrebbero mostrare quanto segue:
Now listening on: http://[::]:5000
<!--NeedCopy-->
Se LogServer utilizza HTTPS, assicurarsi che il suo certificato sia attendibile su tutte le macchine che caricano i log AOT.
Nota:
La porta configurata nella fase di installazione (8080 o 8443 o qualsiasi porta specificata) deve essere utilizzata durante la configurazione dell’URL del server di log in DDC, Storefront, VDA, ecc.
Di solito, richiede 1-10 minuti a seconda dell’hardware in Windows.
Autenticazione TLS reciproca (facoltativo)
Il TLS reciproco (mTLS) fornisce un ulteriore livello di sicurezza tra il Log Server e i client (VDA, DDC, StoreFront, CWA). Quando mTLS è abilitato, sia il client che il server si autenticano a vicenda utilizzando certificati rilasciati dalla PKI aziendale.
mTLS è utile in ambienti in cui:
- I segmenti di rete non sono attendibili o sono condivisi
- È necessario autenticare non solo il Log Server ma anche ogni client di log AOT
- I clienti desiderano impedire ai sistemi non autorizzati di inviare dati di log
- Le politiche normative o di conformità richiedono l’autenticazione basata su certificati.
Sebbene mTLS sia facoltativo, migliora la sicurezza garantendo che solo i componenti Citrix attendibili possano comunicare con il Log Server e che il log server possa verificare ogni connessione in entrata prima di accettare i dati di telemetria.
Requisiti del certificato
Per configurare mTLS, devono essere generati i seguenti certificati:
- aotclient.pfx – Certificato utilizzato dai client di log AOT (VDA, DDC, StoreFront, CWA)
- logserver.pfx – Certificato utilizzato dal Log Server
- enterprise-ca.cer – Il certificato radice o intermedio utilizzato per firmare entrambi i file .pfx
Nota
Saltare questa sezione TLS reciproco se si utilizza Citrix Connector Appliance, poiché non è supportato.
Il file enterprise-ca.cer deve essere importato nell’archivio Autorità di certificazione radice attendibili sia sul Log Server che sui client di telemetria.
I certificati aotclient.pfx e logserver.pfx non devono essere protetti da password.
L’oggetto di aotclient.pfx deve essere CitrixAOTClient, consentendo al client di telemetria di individuare automaticamente il certificato durante l’esecuzione.
Per abilitare mTLS, includere il parametro –ca nel comando di installazione del Log Server. Questo parametro specifica il percorso del certificato enterprise-ca.cer.
# with default path
./InstallLogServer --https --cert logserver.pfx --ca enterprise-ca.cer --port 8443
# with customized path
./InstallLogServer --config /YourPath/LogServer/Config --database /YourPath/LogServer/Data --cert /YourPath/logserver.pfx --ca /YourPath/enterprise-ca.cer --port 8443
# delete temp certificate logserver.pfx in current install directory
sudo rm -rf /YourPath/logserver.pfx
# keep logserver.pfx accessed only by the container process user 'ubuntu'.
sudo chmod 400 LogServer/Config/logserver.pfx
sudo chown ubuntu:ubuntu LogServer/Config/logserver.pfx
<!--NeedCopy-->
Se è richiesta l’autenticazione TLS reciproca, eseguire il seguente comando PowerShell in DDC, Storefront, VDA e altri componenti CVAD con privilegi di amministratore.
# import client cert at the machine aot client
Import-PfxCertificate -CertStoreLocation Cert:\LocalMachine\My\ -FilePath c:\aotclient.pfx
# Verify successful import
Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Subject -like "*AOTclient*" }
# delete temp certificate aotclient.pfx
Remove-Item -Path "C:\aotclient.pfx" -Force
# Ensure LogServer’s certificate is trusted on all machines uploading AOT logs.
<!--NeedCopy-->
Nota:
Il servizio di telemetria è in esecuzione nell’account “network service”, quindi è necessario concedere manualmente a NETWORK SERVICE il controllo completo sulla chiave privata del certificato CitrixAOTClient, utilizzando l’interfaccia grafica certlm.msc.
Premere Win + R, digitare certlm.msc e premere Invio per aprire la console Certificati (computer locale).
Espandere Certificati (computer locale) > Personale > Certificati.
Nel riquadro destro, individuare il certificato rilasciato a CitrixAOTClient.
Aprire “Gestisci chiavi private”
Fare clic con il pulsante destro del mouse sul certificato e selezionare Tutte le attività > Gestisci chiavi private
Nella finestra di dialogo delle autorizzazioni, selezionare Aggiungi, digitare NETWORK SERVICE e fare clic su Controlla nomi (dovrebbe risolversi in NT AUTHORITY\NETWORK SERVICE).
Fare clic su OK per applicare le autorizzazioni.
Se il cliente fornisce certificati autofirmati, procedere come segue:
- Sul lato logserver, logserver.pfx e aotclient.cer sono installati come descritto in precedenza. aotclient.cer svolge il ruolo di enterprise-ca.cer.
- Sul lato client, aotclient.pfx e logserver.cer sono importati come descritto in precedenza. logserver.cer svolge il ruolo di enterprise-ca.cer.
- Per maggiori informazioni, vedere Creare un nuovo certificato
Verificare il Log Server
Aprire il browser su Log Server o VDA o DDC, visitare http://YourLogServerFQDN:8080/Ping
Nel browser verrà visualizzata una stringa di risposta “Pong UTC:08/19/2025 01:03:29 Version: 2511.1.6. L’ora UTC dovrebbe essere l’ora UTC del LogServer. La stringa della versione contiene il nome della release e il numero di build.
Nota:
Modificare la porta 8080 con la porta configurata se non si utilizza quella predefinita e modificare http in https se installato in modalità HTTPS.
Se la verifica del log server fallisce, controllare i seguenti log:
- Eseguire docker logs logserver per controllare i log di docker.
- Per Linux -
$HOME/LogServer/Config/weblogs.txt(modificare $HOME/LogServer con il percorso di installazione effettivo se non si utilizza quello predefinito) - Per Windows -
C:\Users\YourUserName\LogServer\Config\weblogs.txt(Modificare YourUserName con il nome utente effettivo. Modificare C:\Users\YourUserName\LogServer con il percorso di installazione effettivo se non si utilizza quello predefinito)
Configurazione avanzata del Log Server
Su Linux o Windows
Eseguire docker stop logserver per arrestare il logserver
Per impostazione predefinita, il server di log è configurato con i valori seguenti. Per apportare le modifiche, modificare il StartLogServer.sh o StartLogServer.bat se installato in Windows.
-e MAX_RESERVE_DAYS=7
-e MAX_DISK_USAGE_PERCENTAGE=85
-e LOCAL_DOWN_ONLY=true
-e OPENSEARCH_JAVA_OPTS="-Xms2G -Xmx2G"
<!--NeedCopy-->
| Opzioni di configurazione del LogServer | Valore predefinito | Intervallo di valori | Descrizione |
|---|---|---|---|
| LOG_LEVEL | 2 | 0-4 | 0=Trace, 1=Debug, 2=Info, 3=Warning, 4=Error |
| CORS_ORIGINS | “Url” o “url1;url2;url3” | Modificare questo valore per consentire al client CWA H5/Chrome di caricare i log AOT. Supporta più URL separati da “;” | |
| MAX_RESERVE_DAYS | 7 | 1~30 | Il server di log memorizza le voci di log per un numero massimo di giorni in base al campo TimeStamp. I log inseriti 7 giorni fa verranno eliminati. Verifica ogni 10 minuti. |
| MAX_DISK_USAGE_PERCENTAGE | 85 | 10~90 | Il server di log monitora la percentuale di archiviazione dei dati. Se la percentuale di utilizzo supera il 90%, il server di log eliminerà i log meno recenti giorno per giorno fino a quando la percentuale di utilizzo non sarà inferiore al 90%. Verifica ogni 10 minuti. |
| LOCAL_DOWN_ONLY | vero | true/false | Se vero, solo la macchina su cui è installato il server di log può accedere alle API /Download/. Se falso, altre macchine con AuthKey potrebbero accedere alle API /Download/. |
| OPENSEARCH_JAVA_OPTS | “-Xms2G -Xmx2G” | 2G ~ MaxMem/2 | Configurazioni di memoria di Opensearch. Fornire più memoria se ci sono molte macchine che inviano log al server di log. Ad esempio, 0~999 macchine: 2GB; 1000~1999 macchine: 4GB; 2000~9999 macchine: 6GB |
Eseguire ./StartLogServer.sh su Linux per verificare se le modifiche sono state aggiornate.
Eseguire StartLogServer.bat su Windows per verificare se le modifiche sono state aggiornate.
Su Citrix Connector Appliance
Di seguito sono riportati i passaggi per configurare le impostazioni avanzate del server di log su Citrix Connector Appliance tramite API locale.
È possibile eseguirlo su Postman, Curl o PowerShell. Di seguito è riportato un esempio di istruzioni eseguite su Postman:
- Autenticazione: generazione di un JWT
Tutte le chiamate API devono essere autenticate utilizzando un JSON Web Token (JWT). È necessario prima generare un token che viene poi incluso nell’intestazione delle richieste successive.
Passaggio 1.1: Generare il token
Per generare il token, eseguire una richiesta POST all’endpoint $login.
-
Endpoint: POST https://[ip]/$login
-
Corpo: Sarà necessario includere il payload JSON necessario per l’autenticazione (ad esempio, nome utente e password). Se le credenziali sono corrette, l’API restituirà un token.
Copiare questo valore del token per utilizzarlo nei passaggi successivi.
Passaggio 1.2: Autorizzare le chiamate API
Includere il token generato nell’intestazione Authorization per tutte le chiamate API successive. Il token deve essere preceduto da Bearer.
Autorizzazione: Bearer abCD.efGH.ijKL
Un token valido consentirà l’esecuzione della chiamata API. Un token non valido o scaduto verrà rifiutato con un messaggio di errore.
- Aggiunta di impostazioni avanzate
Una volta autenticato, è possibile configurare le impostazioni per un contenitore di destinazione come il logserver Configurare MAX_RESERVE_DAYS
Questa azione configura il MAX_RESERVE_DAYS per il logserver.
- Endpoint: https://[ip]/providers/logserver-provider/environment
- Metodo: PATCH
Corpo della richiesta
{ “MAX_RESERVE_DAYS”: “7” }
Campi
- MAX_RESERVE_DAYS (stringa, obbligatorio): Il valore predefinito è 7 giorni. Il Log Server memorizza le voci di log per un numero massimo di giorni in base al campo TimeStamp. I log inseriti 7 giorni fa verranno eliminati. Verifica ogni 10 minuti.
In questo esempio, lo stiamo modificando a 10 giorni.
Risposte
✅ Successo (204 OK) Indica che l’impostazione è configurata correttamente
Allo stesso modo, possiamo anche regolare la Percentuale massima di utilizzo del disco dal suo valore predefinito di 85. Qui lo stiamo modificando a 90. Quando l’utilizzo del disco raggiunge il 90%, i log meno recenti vengono eliminati per fare spazio a quelli nuovi.
Risposta
✅ Successo (204 OK) Indica che l’impostazione è configurata correttamente