UniFi – import DHCP rezervací z XML

Skript import_unifi.py vytváří rezervace z XML souboru. Vyžaduje Python 3.9+, bez dalších Python knihoven. Pro zjištění ID sítě níže potřebuješ také curl a jq.

1. Vytvoření API klíče

V lokálním rozhraní UDM otevři UniFi Network → Settings → Integrations a vytvoř API klíč. Umístění nabídky a dostupnost klíčů se mohou lišit podle verze.

Použij lokální klíč z UDM. Podpora autentizace klíčem u interního API použitého skriptem závisí na verzi UniFi OS a oprávněních. Dokumentaci pro svou verzi najdeš v sekci Integrations. Dokumentace Ubiquiti

Klíč neukládej do XML ani nesdílej.

2. Zjištění ID sítě

V Bashi nastav skutečnou adresu UDM a zadej klíč skrytě:

UDM='https://192.168.4.1'
read -rsp 'Lokální UniFi API key: ' UNIFI_API_KEY
echo

Vypiš dostupné sítě:

curl --fail-with-body -sk \
  "$UDM/proxy/network/api/s/default/rest/networkconf" \
  -H "X-API-KEY: $UNIFI_API_KEY" \
  | jq '.data[] | { _id, name, ip_subnet }'

Příklad odpovědi:

{
  "_id": "6aaa8d668a88d373001519d3",
  "name": "LAN",
  "ip_subnet": "192.168.4.1/24"
}

Vyber síť podle name a ip_subnet. Hodnotu _id použij jako --network-id při importu.

-k vypíná ověření TLS certifikátu. Pokud má UDM důvěryhodný certifikát, vynech ho. Pokud používáš jinou site, nahraď default v URL jejím krátkým názvem.

3. Příprava XML

Soubor rezervace.xml ulož v UTF-8:

<?xml version="1.0" encoding="UTF-8"?>
<RESERVATIONS>
  <RESERVATION>
    <IP>192.168.4.50</IP>
    <MAC>02:00:00:00:00:50</MAC>
    <NAME>Počítač kancelář</NAME>
    <NOTE>První patro</NOTE>
  </RESERVATION>
  <RESERVATION>
    <IP>192.168.4.51</IP>
    <MAC>02:00:00:00:00:51</MAC>
    <NAME></NAME>
    <NOTE></NOTE>
  </RESERVATION>
</RESERVATIONS>

Vzorové adresy nahraď vlastními.

Pole	Pravidlo
IP	Celá IPv4 adresa ze zvolené sítě.
MAC	Dvojtečky, pomlčky nebo 12 hexadecimálních znaků bez oddělovačů.
NAME	Nepovinné; prázdné nebo chybějící pole se neposílá.
NOTE	Nepovinné; prázdné nebo chybějící pole se neposílá.

Záznamy bez MAC se automaticky přeskočí. Neplatná IP/MAC nebo duplicitní IP/MAC zastaví kontrolu celého souboru před prvním zápisem.

V XML zapisuj & jako & a < jako <. Skript nefiltruje slova „switch“ ani „zrušeno“ — XML má obsahovat požadovaný výběr.

4. Kontrola bez zápisu

Ve složce se skriptem spusť:

python3 import_unifi.py rezervace.xml \
  --network-id 6aaa8d668a88d373001519d3

Skript vypíše JSON požadavky. Nic neodesílá a nepotřebuje API klíč.

5. Import do UniFi

python3 import_unifi.py rezervace.xml \
  --network-id 6aaa8d668a88d373001519d3 \
  --udm https://192.168.4.1 \
  --apply

Skript si vyžádá klíč skrytě. Pokud už je načtený v proměnné z kroku 2, můžeš ho skriptu předat:

export UNIFI_API_KEY

Pro certifikát podepsaný vlastní autoritou, kterému počítač nedůvěřuje, lze přidat --insecure. Tím vypneš ověření TLS certifikátu, stejně jako curl -k.

Pro jinou site přidej:

--site NAZEV_SITE

6. Chování při chybě

Skript vytváří nové rezervace, existující automaticky nepřepisuje.

• api.err.MacUsed: MAC už v UniFi existuje a vyžaduje aktualizaci.
• 401 / 403: problém s autentizací, oprávněním nebo podporou API klíče.
• Při první chybě se import zastaví; předchozí úspěšné zápisy zůstávají.
• Po timeoutu ověř stav posledního záznamu v UniFi před opakováním.
• Před opětovným spuštěním odstraň z XML již importované záznamy.

Skript nekontroluje skutečnou obsazenost IP ani podsíť na UDM. Všechny záznamy odešle do sítě určené parametrem --network-id.