Connettere i Dispositivi

IronFlock supporta diversi modi per connettere i dispositivi, a seconda dell’hardware e del sistema operativo. Non hai hardware a disposizione? Puoi simulare un dispositivo sul tuo laptop in pochi minuti.

Prerequisiti

Prima di connettere un dispositivo, assicurati di avere:

1. Un progetto creato su IronFlock
2. Una voce dispositivo creata all’interno di quel progetto (clicca NUOVO DISPOSITIVO nel pannello Impostazioni -> Dispositivi del progetto.)
3. Il file di configurazione del dispositivo scaricato (.flock)

Hai perso il file .flock? Puoi scaricarlo di nuovo in qualsiasi momento: apri il dispositivo nella barra laterale del progetto, vai su Manutenzione e fai clic su Scarica file di configurazione. È la stessa configurazione, non un nuovo dispositivo. Servono privilegi maintain sul dispositivo. Vedi Manutenzione Dispositivo.

Dispositivo su una rete aziendale con restrizioni? Pianifica la configurazione di rete prima di installare — è il motivo più comune per cui un dispositivo appena installato resta offline:

• Firewall o proxy basato sull’identità: la regola che autorizza il dispositivo deve essere legata al dispositivo stesso, mai a un utente che ha effettuato l’accesso — altrimenti il dispositivo perde l’accesso alla rete ogni volta che la sessione di quell’utente scade. Vedi Firewall e Proxy Basati sull’Identità.
• Proxy HTTP aziendale: l’agente e Docker devono esserne informati in modo esplicito — vedi Dietro un Proxy Aziendale → Dispositivi Edge.
• Connessione a un Appliance on-premises: il dispositivo deve raggiungere direttamente le porte di servizio dell’Appliance — oppure, quando l’Appliance usa HTTPS con il tuo certificato aziendale, solo la porta 443, con la tua CA radice aziendale considerata attendibile sul dispositivo. Vedi Connettività dei dispositivi nella guida all’Appliance.
• Deriva dell’orologio: i firewall aziendali bloccano di solito i server orari pubblici forniti con un sistema appena installato, così l’orologio del dispositivo va alla deriva senza segnali — configura il tuo server NTP interno. Vedi Sincronizzazione oraria (NTP).

Firewall e Proxy Basati sull’Identità

Ogni dispositivo edge esegue l’agente IronFlock come servizio di sistema non presidiato. Si avvia al boot, resta connesso giorno e notte e continua a installare app, scaricare immagini e aggiornarsi da solo — che qualcuno abbia effettuato l’accesso sul dispositivo oppure no. Questo vale ovunque venga eseguita la tua piattaforma: nel cloud IronFlock, nel tuo cloud privato o su un Appliance on-premises.

Le reti OT sono sempre più spesso protette da firewall e proxy basati sull’identità (identity-aware), che concedono l’accesso in base all’identità della directory anziché all’indirizzo di rete. Se la regola che autorizza un dispositivo edge è legata all’utente che vi ha effettuato l’accesso, il dispositivo perde la rete ogni volta che la sessione di quell’utente scade:

• Le connessioni già aperte continuano a funzionare, quindi il dispositivo risulta ancora online.
• Ogni nuova connessione viene scartata in silenzio — installazioni di app, download delle immagini, aggiornamenti dell’agente e riconnessioni falliscono.
• Dopo il successivo riavvio dell’agente o del dispositivo, non riesce più a riconnettersi e resta offline finché qualcuno non effettua di nuovo l’accesso sul dispositivo o la regola non viene modificata.

Chiedi al tuo team di rete di legare la regola al dispositivo, mai a una persona:

Come si applica ai prodotti più diffusi:

• Check Point Identity Awareness: nell’Access Role seleziona la macchina (oggetto computer o gruppo) anziché gli utenti. Le identità delle macchine vengono rinnovate dall’attività di dominio del computer stesso; se sul tuo gateway possono scadere, usa invece un oggetto di rete.
• Palo Alto Networks User-ID: gli account computer non producono mappature IP-utente, quindi usa un oggetto indirizzo, un tag o Device-ID.
• Fortinet FSSO e firewall analoghi basati sulla directory: usa un oggetto indirizzo per il dispositivo, oppure l’indirizzo dinamico assegnato dal tuo controllo degli accessi alla rete.
• Zscaler, Prisma Access e altri gateway di sicurezza cloud: registra la rete dei dispositivi come location di tipo IoT o server (una sorgente attendibile), così il traffico dei dispositivi viene identificato in base alla location anziché all’utente.

Non si tratta di un’esenzione dalla tua policy basata sull’identità — il dispositivo viene identificato tramite l’identità che possiede effettivamente. Se utilizzi un Appliance on-premises, lo stesso vale per l’host dell’Appliance: vedi Identità di Rete per gli Host IronFlock.

Come riconoscere il problema. Un dispositivo che resta online mentre installazioni di app, download delle immagini o aggiornamenti dell’agente falliscono per timeout — e i ping continuano a funzionare — indica una regola di identità scaduta, non un guasto del dispositivo. Non riavviare l’agente né il dispositivo finché una nuova connessione dal dispositivo non torna ad andare a buon fine: la sessione ancora aperta è l’unica che funziona, e nel frattempo mantiene il dispositivo gestibile da remoto.

Prova Prima: Simula un Dispositivo sul Tuo Laptop

Non hai bisogno di hardware fisico per esplorare IronFlock. L’app FlockFlasher può eseguire l’agente IronFlock direttamente sul tuo laptop, così il tuo laptop impersona un dispositivo reale all’interno del tuo progetto — perfetto per testare app e dashboard prima di passare all’hardware vero e proprio.

1. Installa Docker Desktop (o Docker Engine su Linux) e assicurati che sia in esecuzione.
2. Scarica e installa l’app FlockFlasher per il tuo sistema operativo.
3. Fai doppio clic sul file .flock scaricato del tuo dispositivo — si apre in FlockFlasher e il dispositivo appare nell’elenco. (In alternativa, apri FlockFlasher e aggiungi il file tramite il pulsante +.)
4. Clicca Test Device (▶) sulla voce del dispositivo. FlockFlasher scarica automaticamente l’agente IronFlock al primo utilizzo e lo avvia con la configurazione del tuo dispositivo.

Il tuo laptop ora agisce come questo dispositivo all’interno del tuo progetto IronFlock: appare online e puoi installare ed eseguire app su di esso esattamente come su un dispositivo reale. Le app vengono eseguite come container Docker sul tuo laptop.

Quando hai finito, interrompi il test in FlockFlasher. In seguito potrai usare lo stesso file .flock per configurare il dispositivo reale — assicurati solo che una determinata configurazione del dispositivo venga eseguita da una sola macchina alla volta.

Metodo 1: Flash di una Scheda SD

Ideale per Raspberry Pi e altri dispositivi ARM che si avviano da schede SD.

1. Scarica l’app FlockFlasher per il tuo sistema operativo.
2. Inserisci una scheda SD (minimo 16 GB) nel computer.
3. Apri FlockFlasher e clicca il pulsante + per caricare il file .flock.
4. Seleziona l’unità della scheda SD (FlockFlasher rileva automaticamente le unità esterne).
5. Scegli l’immagine corretta per il tuo dispositivo (Raspberry Pi 3/4, Zero, ecc.).
6. Facoltativamente configura il WiFi in modo che il dispositivo possa connettersi a destinazione.
7. Clicca Flash e attendi il completamento di scrittura, validazione e configurazione.
8. Inserisci la scheda SD nel dispositivo e accendilo.

Il dispositivo dovrebbe andare online entro 20 minuti.

Avviso: Il processo di flashing cancella tutti i dati sull’unità selezionata. FlockFlasher nasconde le unità interne per impostazione predefinita, ma verifica sempre la tua selezione.

Metodo 2: Installatore USB per PC Industriali

Per dispositivi AMD64 con boot EFI (es. Siemens SIMATIC Box IPC).

1. Inserisci una chiavetta USB (minimo 16 GB) e apri FlockFlasher.
2. Carica il file .flock e seleziona l’unità USB.
3. Seleziona l’immagine Industrial PC x86_64 (EFI).
4. Clicca Flash e attendi il completamento.
5. Se necessario, modifica l’ordine di avvio nel BIOS del dispositivo per avviarsi da USB.
6. Inserisci la chiavetta USB e accendi il dispositivo.

Il dispositivo dovrebbe andare online entro 60 minuti.

Metodo 3: Installazione Personalizzata

Per dispositivi che mantengono il loro sistema operativo Linux esistente. Ideale per NVIDIA Jetson e hardware personalizzato.

Nota: Questo metodo di installazione manuale è pensato per hardware di produzione reale come PC industriali, gateway e dispositivi embedded — non per laptop. Se vuoi solo provare IronFlock sul tuo laptop, segui invece Prova Prima: Simula un Dispositivo sul Tuo Laptop — non è richiesta alcuna installazione manuale dell’agente.

Dispositivi Linux / Unix

1. Accedi tramite SSH al dispositivo.
2. Copia il file .flock dal computer al dispositivo:

   scp mydevice.flock user@device-ip:/home/user/

3. Scarica ed esegui l’installer:

   curl -fsSL https://instance-registry.ironflock.com/dl/device-init/install.sh | sudo bash -s -- -c mydevice.flock

   Su un’Appliance IronFlock? I comandi sono gli stessi. Il dispositivo ha bisogno dell’accesso a internet durante l’installazione. In seguito deve raggiungere solo l’Appliance (vedi Dispositivi edge).

install.sh scarica lo strumento di setup ironflock-init per la CPU del dispositivo, ne verifica la firma OpenPGP con la chiave IronFlock incorporata nello script e lo esegue con gli argomenti che gli passi. Senza argomenti scarica soltanto ./ironflock-init nella directory corrente; avvialo poi con sudo ./ironflock-init -c mydevice.flock.

ironflock-init installa Docker (se manca) e l’agent del dispositivo e configura:

• un utente SSH per il proprietario del progetto — accesso solo con chiave (la chiave del dispositivo) e sudo senza password;
• il WiFi dal file .flock, tramite NetworkManager;
• un banner di accesso.

Non tocca gli aggiornamenti di sicurezza automatici e non riavvia il dispositivo a meno che tu non passi --reboot. Tutto ciò che modifica viene registrato in /opt/ironflock/device-init/installed.json, così il comando remove annulla esattamente quello:

curl -fsSL https://instance-registry.ironflock.com/dl/device-init/install.sh | sudo bash -s -- remove

Altre opzioni di ironflock-init:

• -a — usa i valori predefiniti, senza domande
• --disable-suspend (-s) — impedisce al dispositivo di entrare in sospensione
• --reboot — riavvia il dispositivo al termine del setup
• --update-config (-u) — sostituisce il file .flock di un dispositivo già installato
• --http-proxy, --https-proxy, --no-proxy — instradano il setup attraverso un proxy
• --download-base — scarica da un altro server

Sul dispositivo l’agent si trova in /opt/ironflock/device-agent ed è eseguito come servizio systemd ironflock-device-agent. Verificalo con systemctl status ironflock-device-agent; il log è disponibile con journalctl -u ironflock-device-agent e in /var/log/ironflock/device-agent.log. La configurazione è /opt/ironflock/device-agent/device-config.flock (leggibile solo da root; non c’è più una copia in /boot), Docker conserva i suoi dati in /opt/ironflock/device-agent/docker-apps e i dati delle app restano in /apps.

L’agent si aggiorna da solo: non esiste un gestore di aggiornamenti separato. Gli aggiornamenti sono firmati e verificati, e un aggiornamento non riuscito viene annullato automaticamente. Vengono applicati solo all’avvio dell’agent o quando un utente avvia l’aggiornamento in Studio.

I dispositivi installati prima di ottobre 2026 usavano /opt/reagent e il servizio reagent.service. Appena uno di essi esegue l’agent 1.3.x, passa da solo alla struttura descritta sopra — Docker e le app si riavviano una volta — e /opt/reagent resta come collegamento.

Dietro un proxy aziendale? Fornisci il proxy anche al download dell’installer e aggiungi --http-proxy / --https-proxy agli argomenti del passo 3, così ironflock-init configura per te il motore Docker. Per il comando completo e i passaggi sulla CA aziendale consulta Dietro un Proxy Aziendale.

Facoltativo: verifica prima l’installer

Per esaminare lo script prima che venga eseguito come root, scaricalo insieme alla sua firma e verificalo con la chiave bootstrap di IronFlock:

curl -fsSLO https://instance-registry.ironflock.com/dl/device-init/install.sh
curl -fsSLO https://instance-registry.ironflock.com/dl/device-init/install.sh.asc
curl -fsSL https://instance-registry.ironflock.com/dl/device-init/ironflock-bootstrap.asc | gpg --import
gpg --verify install.sh.asc install.sh

gpg deve segnalare una firma valida di IronFlock Bootstrap <[email protected]> con l’impronta F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788. Poi esegui lo script verificato:

sudo bash install.sh -c mydevice.flock

Dispositivi Windows

1. Installa Docker Desktop sul dispositivo e attiva Start Docker Desktop when you sign in nelle impostazioni di Docker Desktop. Per i dispositivi non presidiati, configura anche l’accesso automatico di Windows in modo che Docker sia disponibile dopo un riavvio senza che nessuno effettui l’accesso.

2. Scarica device-agent.exe sul dispositivo. Il browser lo salva nella cartella Download.

3. Copia il file .flock sul dispositivo e mettilo nella stessa cartella Download.

4. Apri PowerShell con i diritti di amministratore: apri il menu Start, digita PowerShell, seleziona Esegui come amministratore e conferma la richiesta di Controllo dell’account utente con Sì. Il titolo della finestra deve iniziare con Amministratore:. In una normale finestra di PowerShell, l’installazione si interrompe con il messaggio this command must be run from an elevated (Administrator) prompt.

5. Una finestra di PowerShell come amministratore si apre in C:\Windows\System32. Spostati nella cartella Download e verifica che entrambi i file siano presenti:

   cd $env:USERPROFILE\Downloads
   dir device-agent.exe, *.flock

6. Installa e avvia l’agente come servizio Windows:

   .\device-agent.exe service install -config .\myaccount_myproject_mydevice.flock

   Sostituisci myaccount_myproject_mydevice.flock con il nome del tuo file — Studio lo nomina in base al proprietario del progetto, al progetto e al dispositivo. Digita le prime lettere del nome e premi Tab per completarlo. Non omettere .\ davanti a device-agent.exe: senza di esso PowerShell non esegue un programma dalla cartella corrente.

   Il servizio ironflock-device-agent si avvia subito e poi a ogni accensione, si riavvia automaticamente in caso di errore e mantiene l’agente aggiornato. Aggiungi -noStart per installarlo senza avviarlo. Il programma di installazione copia device-agent.exe e il file .flock nella cartella dell’agente, quindi in seguito puoi eliminarli entrambi dalla cartella Download.

Sul dispositivo l’agente risiede in %ProgramData%\IronFlock\DeviceAgent: device-agent.exe, la configurazione device.flock, il log device-agent.log e i dati delle app in apps\. Gli aggiornamenti sono firmati e verificati e un aggiornamento non riuscito viene annullato automaticamente; vengono applicati solo all’avvio dell’agente o quando un utente avvia l’aggiornamento in Studio.

Controllare l’agente e leggerne il log

La cartella dell’agente è leggibile solo dagli amministratori, quindi esegui anche questi comandi in una finestra di PowerShell come amministratore. Verifica che il servizio sia in esecuzione:

Get-Service ironflock-device-agent

Status deve essere Running. Mostra le ultime 100 righe del log dell’agente e continua a stampare le nuove righe man mano che l’agente le scrive:

Get-Content "$env:ProgramData\IronFlock\DeviceAgent\device-agent.log" -Tail 100 -Wait

Premi Ctrl+C per smettere di seguire il log. Per cercare nel log solo gli errori:

Select-String -Path "$env:ProgramData\IronFlock\DeviceAgent\device-agent.log" -Pattern "error" | Select-Object -Last 20

Per riavviare l’agente, usa i suoi comandi. Il dispositivo resta offline finché l’agente non è di nuovo in esecuzione:

& "$env:ProgramData\IronFlock\DeviceAgent\device-agent.exe" service stop
& "$env:ProgramData\IronFlock\DeviceAgent\device-agent.exe" service start

Non usare Restart-Service per l’agente. L’agente può impiegare fino a 15 secondi per fermarsi e Restart-Service può rinunciare prima, lasciando il servizio fermo.

I dispositivi Windows installati prima dell’agente 1.4.0 usavano %ProgramData%\IronFlock\Reagent e il servizio reagent. L’agente 1.4.0 sposta un dispositivo di questo tipo nella struttura descritta sopra: l’agente e le sue app si riavviano una volta.

Dietro un proxy aziendale? Aggiungi -proxy http://proxy.example.com:3128 al comando service install e configura il proxy di Docker Desktop in Settings → Resources → Proxies. Consulta Dietro un Proxy Aziendale per i dettagli e i passaggi per la CA aziendale.

Dispositivo Windows aggiunto al tuo dominio? Il servizio dell’agente viene eseguito come LocalSystem, che qualcuno abbia effettuato l’accesso oppure no, quindi una regola del firewall legata all’utente connesso non lo copre. Fai legare la regola all’account computer del dispositivo — vedi Firewall e Proxy Basati sull’Identità.

Sincronizzazione oraria (NTP)

L’agent del dispositivo ha bisogno di un orologio preciso. L’handshake TLS con la piattaforma, i token che autorizzano il download delle immagini e il timestamp di ogni punto dati pubblicato dal dispositivo dipendono da esso. Un dispositivo il cui orologio è sfasato di più di 15 minuti viene inoltre rifiutato dall’archiviazione file con CLOCK_SKEW.

In una rete aziendale questo è un passo di configurazione, non una cosa scontata: l’NTP in uscita sulla porta UDP 123 è spesso bloccato, quindi i server orari pubblici forniti con il sistema operativo sono irraggiungibili e l’orologio va alla deriva senza alcun errore visibile. Chiedi al reparto IT il server orario interno e configuralo sul dispositivo, oppure fai abilitare l’UDP 123 in uscita per la rete dei dispositivi.

Linux

Con systemd-timesyncd (predefinito su Debian e Ubuntu):

sudo mkdir -p /etc/systemd/timesyncd.conf.d
sudo tee /etc/systemd/timesyncd.conf.d/corporate.conf > /dev/null <<'EOF'
[Time]
NTP=ntp.your-company.com
EOF
sudo systemctl restart systemd-timesyncd
timedatectl status

Con chrony:

echo "server ntp.your-company.com iburst" | sudo tee -a /etc/chrony/chrony.conf
sudo systemctl restart chrony
chronyc sources

timedatectl status deve riportare System clock synchronized: yes.

Windows

Da un prompt con privilegi di amministratore:

w32tm /config /manualpeerlist:"ntp.your-company.com" /syncfromflags:manual /update
w32tm /resync
w32tm /query /status

I dispositivi installati con un’immagine IronFlock pronta all’uso (metodi 1 e 2) si sincronizzano per impostazione predefinita con server orari pubblici. Su una rete che li blocca, consenti l’UDP 123 in uscita per la sottorete dei dispositivi, oppure configura il server orario interno via SSH dopo il primo avvio, esattamente come mostrato sopra per Linux.

Verifica della Connessione

Dopo la connessione, controlla lo stato del dispositivo nel tuo progetto:

• Indicatore verde — Il dispositivo è online e comunica con IronFlock.
• Indicatore rosso — Il dispositivo è offline. Controlla la connessione di rete e assicurati che l’agente sia in esecuzione.
• Verde, ma installazioni di app, download delle immagini o aggiornamenti dell’agente vanno in timeout — una regola del firewall potrebbe aver smesso di autorizzare nuove connessioni dal dispositivo. Leggi Firewall e Proxy Basati sull’Identità prima di riavviare qualsiasi cosa.

La vista mappa del dispositivo mostra la posizione geografica di tutti i dispositivi nel progetto.