Riferimento
Importare ed esportare in YAML
La rete di un canvas in YAML, da copiare, scaricare e ricaricare; e la bozza Terraform.
I dispositivi e le connessioni del canvas aperto si possono scrivere come testo YAML, copiare o scaricare, e rileggere da un file .yaml o .yml. È un modo per guardare una rete come testo, per tenerla in un repository, o per costruirne una con uno script. Non è il modo di salvare un progetto: lo YAML contiene la rete, il punto in cui è disegnato ogni dispositivo e i riquadri, e non le impostazioni, i template o gli altri canvas; il file del progetto contiene tutto. La stessa finestra offre anche un'esportazione Terraform, che è soltanto una bozza (più sotto).
Esportare
«Import/Export», nella barra a sinistra, apre la finestra; la prima scheda è l'esportazione. «Formato:» sceglie tra YAML e «Terraform HCL (bozza)». Il testo è mostrato come verrà scritto, con il numero di righe e il numero di dispositivi e di connessioni del canvas. «Copia negli appunti» lo copia; il secondo pulsante lo scarica come <nome del progetto>-topology.yaml, con il nome in minuscolo e ogni carattere che non sia una lettera, una cifra, un trattino o un trattino basso trasformato in un trattino. Un canvas senza dispositivi non ha nulla da esportare, e i due pulsanti sono disattivati.
Si esporta solo il canvas aperto. Un progetto con più canvas si esporta un canvas alla volta, cambiando canvas e riaprendo la finestra.
I riquadri del canvas sono scritti anch'essi, insieme alla posizione di ogni dispositivo, così un riquadro resta intorno ai suoi dispositivi quando il file viene ricaricato. I riquadri sono scritti anche se sono nascosti (Vista → «Mostra i riquadri»).
Importare
La seconda scheda serve a caricare un file: lo si trascina nella zona indicata, oppure ci si fa clic per sceglierlo. Si accettano solo .yaml e .yml; per qualunque altro file compare l'avviso Formato non supportato. Usa un file .yaml o .yml. Non cambia ancora nulla: la finestra mostra il nome del file, quanti dispositivi e quante connessioni contiene, l'elenco «Dispositivi trovati» con il tipo e l'indirizzo di ciascuno e, se il file ha dei problemi, l'elenco «Avvisi».
«Modalità:» dice dove vanno i dispositivi:
- «Sostituisci topologia» svuota prima il canvas, dispositivi, connessioni e riquadri, e carica il file al suo posto. Se sul canvas c'è qualcosa, prima arriva una domanda: «Sostituire la topologia?», che dice quanti dispositivi, connessioni e riquadri verranno tolti. «Sostituisci» prosegue, «Annulla» o Esc lasciano il canvas com'è. Modifica → «Annulla», o Ctrl + Z, rimette il canvas com'era, in un passo solo. Le impostazioni di rete del progetto e i nomi delle sue VLAN non vengono toccati.
- «Aggiungi alla topologia» lascia ciò che c'è sul canvas e aggiunge i dispositivi, le connessioni e i riquadri del file, con ID nuovi. Il gruppo nuovo va a destra del disegno che c'è già, allineato in alto con esso e a 120 unità di distanza, quindi non finisce mai sopra ciò che hai disegnato; la disposizione dentro il gruppo, e i riquadri intorno ai suoi dispositivi, restano quelle del file. Un dispositivo il cui nome è già sul canvas riceve il primo nome libero (
PC-1diventaPC-1-1), e un avviso dice quali.
«Importa» esegue l'importazione, e un avviso dice quanti dispositivi e quante connessioni sono stati aggiunti. Il pulsante resta disattivato se il file non contiene nessun dispositivo.
Un file scritto dall'app dice dove è disegnato ogni dispositivo (position). Un file che non lo dice, per esempio uno scritto a mano o da uno script, ha i dispositivi disposti su una griglia: tante colonne quanto la radice quadrata del numero, arrotondata per eccesso, a 250 unità l'una dall'altra in orizzontale e 200 in verticale, a partire da 100, 100, nell'ordine del file. Vista → Disposizione automatica rimette in ordine il disegno (chiede prima, e Ctrl + Z la annulla).
L'importazione accetta il file come lo scrive l'app, con tutto sotto una chiave pixelcake:, e anche le stesse liste all'inizio del file senza pixelcake: intorno. Ciò che manca prende un valore predefinito: un dispositivo senza nome si chiama Device-1, Device-2…, uno senza tipo è un PC, un'interfaccia senza stato è accesa. Ciò che non va viene detto negli avvisi:
| Avviso | Quando |
|---|---|
Errore di lettura del file YAML: … |
Il testo non è YAML; segue il motivo del lettore, con la riga. |
Il file YAML non contiene dati validi |
Il file è vuoto, oppure è un valore solo. |
Struttura YAML non riconosciuta |
La chiave pixelcake: contiene qualcosa che non è un insieme di campi. |
Nessun dispositivo trovato nel file |
Non c'è la lista devices, o è vuota. |
Dispositivo 3: formato non valido, ignorato |
Una voce di devices non è un insieme di campi. |
Router-1: IP "abc" non valido |
L'indirizzo di un dispositivo o di una porta non è fatto di quattro gruppi di al massimo tre cifre. Si controlla solo la forma: 300.1.1.1 passa. |
Porta 1: VLAN 5000 fuori intervallo (1–4094), non importata |
Una VLAN di una porta, di un dispositivo (SW-1: VLAN …) o di una connessione (Connessione 3: VLAN …) è fuori dall'intervallo. Non viene importata; le altre dell'elenco sì. |
Nomi usati più volte, … |
Due dispositivi hanno lo stesso nome, confrontato come lo confronta il terminale: senza badare alle maiuscole né agli spazi intorno. Il primo tiene il nome, ognuno dei successivi riceve il primo nome libero, PC-1-1, PC-1-2…, e l'avviso elenca ogni "vecchio" → "nuovo". Le connessioni che citano quel nome vanno al primo dispositivo. |
Riquadro 2: senza posizione o dimensioni, ignorato |
Una voce di areas non ha position e size, o ne ha di non disegnabili. |
FW-Edge: regola 2 incompleta o non valida, ignorata |
Una regola ha bisogno di allow o deny, di un servizio e di entrambe le estremità. Per rotte, inoltri e record DNS l'avviso è dello stesso tipo (rotta 1 senza destinazione o prossimo salto, inoltro 1 incompleto o non valido, record DNS 1 senza nome o indirizzo). Gli altri tengono il loro ordine. |
Porta 2: server DHCP senza primo o ultimo indirizzo, ignorato |
Un intervallo DHCP senza start o senza end. |
Connessione 4: dispositivo di partenza «PC-9» non trovato |
Una connessione nomina un dispositivo che il file non ha (così anche per la destinazione). La connessione viene lasciata fuori. |
Connessione 2: porta 3 non trovata su «A», estremità non assegnata |
La porta, o la scheda, nominata da una connessione non è su quel dispositivo. La connessione resta, e all'estremità viene assegnata un'interfaccia libera quando il file viene caricato. |
Connessione 2: porta 1 di «B» già usata da un'altra connessione, estremità non assegnata |
Due connessioni nominano la stessa interfaccia. La prima la tiene. |
Un file con degli avvisi si può importare lo stesso: ciò che non va viene lasciato fuori e il resto viene letto.
I campi
L'inizio del file in cui viene esportata la rete di esempio «Ufficio: due reti e un router»:
# PixelCake Topology Export
# Generated: 2026-11-17
# Devices: 7 | Connections: 6
pixelcake:
version: "1.0"
project: Progetto senza nome
exported: 2026-11-17
devices:
- name: Router-1
type: Router
template_id: tpl-router
ip: 192.168.10.1
subnet: 255.255.255.0
location: Sala server
ports:
- id: 1
name: LAN Uffici
enabled: true
ip: 192.168.10.1
subnet: 255.255.255.0
speed: auto
mode: lan
…
connections:
- source: PC-1
target: SW-Office
source_nic: eth0
target_port: 1
type: access
bandwidth: 1 Gbps
…Le righe di commento in alto e version, project e exported servono a chi legge il file: l'importazione non li usa. Una connessione nomina i suoi due dispositivi per nome, e la porta o la scheda a ciascuna estremità: source_port: 8 per una porta, source_nic: eth0 per una scheda (con il suo nome).
Che cosa contiene un dispositivo, quando ce l'ha: type, template_id (che tipo di server o di storage è), ip, subnet, gateway, vendor, location, notes, vlan (l'elenco del dispositivo), stp, position (dove è disegnato, come {x: 100, y: 50}, scritta per ultima), e poi le liste. Una porta ha id, name, enabled, ip, subnet, speed, mode, vlan (un numero per una porta di accesso, una lista per un trunk), poe, nat, dhcp_server, security_zone, description. Una scheda ha name, enabled, ip, subnet, gateway, dns, speed, mac, description, e dhcp: true al posto degli indirizzi quando prende i suoi da un server. Le liste sono routes (destination, via), firewall_rules, port_forwards e dns_records.
Regole e inoltri sono scritti nell'ordine in cui vengono letti, che è l'ordine che conta:
routes:
- destination: 192.168.0.0/16
via: 10.0.0.1
description: reti interne
firewall_rules:
- action: allow
service: web
from: untrust
to: 172.16.0.10
description: portale clienti
- action: allow
service: email
from: untrust
to: 192.168.30.40
description: posta in arrivo
port_forwards:
- service: web
interface: 3
to: 172.16.0.10
description: portale clientiÈ una parte di FW-Edge nella rete dell'azienda. L'indirizzo che una scheda riceve dal DHCP non si scrive mai, e nemmeno l'indirizzo che corrisponde a un nome: si ricavano dal disegno.
I riquadri vengono dopo le connessioni, uno per voce, con l'etichetta, il colore (slate, green, amber, red, violet o teal), l'angolo in alto a sinistra e le dimensioni, nelle stesse unità delle posizioni dei dispositivi:
areas:
- label: Core
color: violet
position: {x: 80, y: 20}
size: {width: 300, height: 200}Limiti
Limiti
- Lo YAML non è il progetto. Lascia fuori le impostazioni di rete del progetto, i nomi delle VLAN, i template personalizzati, il colore di una connessione e gli altri canvas. Per conservare un progetto si salva il file del progetto.
- I nomi sono le chiavi. Una connessione trova i suoi dispositivi per nome, quindi due dispositivi con lo stesso nome non si distinguono: chi legge rinomina i successivi e lo dice, e una connessione che cita il nome in comune va al primo. Un nome che lo YAML leggerebbe come numero o come booleano, come
10,1.50otrue, viene tenuto come il testo con cui è stato scritto, e l'app lo scrive tra virgolette. - Si controlla solo la forma. Una maschera, un gateway, una zona, un servizio o un tipo che l'app non conosce viene letto così com'è: un dispositivo di tipo
Bananaviene importato. La simulazione lo tratta poi come può. - L'esportazione Terraform è una bozza. Scrive tipi di risorsa segnaposto (
network_switch,compute_instance…) e non nomina nessun provider, quinditerraform applynon ha nulla a cui applicarla. Contiene indirizzi, VLAN, porte, schede, record DNS e connessioni, e lascia fuori rotte, regole del firewall, inoltri e note. Due dispositivi i cui nomi differiscono solo per la punteggiatura (PC 1ePC-1) ricevono lo stesso nome di risorsa, e le virgolette in un nome non vengono protette. Serve a mostrare dove va il progetto, non a essere usata. - Non c'è l'importazione di Terraform. Leggere un file
.tfstate, o un qualsiasi file Terraform, non è previsto: si importa solo YAML.