Flagi, wyjście i kody wyjścia

Te zasady obowiązują każde polecenie ironflock i skrypt może na nich polegać. Strona każdego polecenia podaje tylko to, co polecenie dodaje od siebie.

Wiersz poleceń ma jedną z dwóch postaci:

ironflock <group> <verb> [flags]      ironflock agent install -c device.flock
ironflock <verb> [flags]              ironflock version

Grupa to produkt: agent dla agenta urządzenia, appliance dla IronFlock Appliance, os dla IronFlockOS. Czasownik znaczy to samo w każdej grupie. Polecenia dotyczące całej maszyny nie należą do żadnej grupy. ironflock i ironflock <group> bez czasownika wypisują swoją pomoc. Żadne polecenie nie przyjmuje argumentów pozycyjnych, chyba że jego strona mówi inaczej; wszystko inne to flagi. login i device to nazwy zarezerwowane: odpowiadają, że są zarezerwowane, i kończą się kodem wyjścia 2.

Flagi globalne

Każde polecenie akceptuje te flagi. Wszystkie poza --help mogą stać przed nazwą polecenia lub po niej: ironflock --json version i ironflock version --json to to samo.

Flagi o stałych nazwach

Nazwa flagi znaczy to samo w każdym poleceniu, które ją ma. -c i -d to jedyne krótkie flagi poza -h.

Bazowy adres pobierania i proxy

Bazowy adres pobierania pochodzi z --download-base, potem ze zmiennej środowiskowej IRONFLOCK_DL_BASE, a w przeciwnym razie jest to https://instance-registry.ironflock.com/dl. Gdy nie podano ani jednego, ani drugiego, agent install, doctor, os install i os update przed chmurą sięgają do kopii lustrzanej pobierania tego Appliance, który wskazuje plik .flock urządzenia (Urządzenia IronFlock Appliance).

Proxy pochodzi z flag, potem z HTTP_PROXY, HTTPS_PROXY i NO_PROXY (lub ich wersji pisanych małymi literami). Wyjątkiem jest agent configure: zmienia proxy urządzenia wyłącznie na podstawie swoich flag, a środowisko polecenia nic tu nie zmienia. Adres URL proxy wygląda jak http://proxy.example.com:3128; działają też https:// i socks5://, a adres URL bez schematu oznacza http://. Gdy proxy wymaga logowania, adres URL podaje użytkownika, jak w http://[email protected]:3128, a hasło podaje --proxy-password-file (zobacz Sekrety). Urządzenia za proxy opisuje strona Za firmowym proxy.

Wyjście i JSON

stdout przenosi wynik i nic poza nim. To jeden krótki tekst dla człowieka albo, z --json, dokładnie jeden obiekt JSON w jednym wierszu. --help również trafia na stdout. Jedynym wyjątkiem jest agent logs, którego wynikiem jest log: z --json zapisuje jeden obiekt JSON na każdy wiersz logu.

stderr przenosi całą resztę: postęp, wyjście narzędzi uruchamianych przez polecenie (apt, instalator Dockera), ostrzeżenia, pytania i błędy.

Dzięki temu przekierowanie lub podstawienie polecenia dostaje sam wynik, a skrypt, który chce ciszy, przekierowuje stderr:

# Wynik jako tekst w pliku; postęp i ostrzeżenia nadal widać w terminalu
ironflock status > result.txt
 
# Wynik jako JSON w zmiennej powłoki, bez komunikatów ze stderr
result=$(ironflock status --json 2>/dev/null)

Nazwy pól w JSON są w stylu snake_case. Wynik ma pole action, gdy polecenie coś zmieniło, na przykład "installed", "configured" lub "removed". Z czasem dochodzą nowe pola, a w obrębie wersji głównej żadne pole nie zmienia nazwy ani nie znika. Program odczytujący wynik pomija pola, których nie zna. Przy kilku maszynach --json zapisuje zamiast tego jeden wiersz na maszynę (zobacz Zdalne maszyny przez SSH).

Postęp

Długi krok pokazuje na stderr, jak daleko doszedł: w terminalu jako pasek, poza terminalem jako wiersz co 10%. Z --json stdout nadal dostaje dokładnie jeden obiekt JSON, czyli wynik, a stderr dostaje postęp jako zdarzenia, po jednym obiekcie JSON w wierszu:

{"event":"progress","phase":"writing","done":104857600,"total":412345678}

os install czyta plik obrazu dwa razy przed restartem: checking porównuje jego SHA-256 z podpisanym katalogiem, a preparing raz rozpakowuje obraz, aby znaleźć jego partycję IRONFLOCKOS, umieścić na niej plik .flock urządzenia i ustawienia sieciowe oraz obliczyć sumy kontrolne tego, co zapis umieści na dysku. W terminalu fazy te są widoczne jako Checking i Preparing.

Zdarzenie pojawia się, gdy faza się zaczyna (done wynosi 0), przy każdej zmianie pełnego procentu i gdy faza się kończy (done równa się total). Wznowione pobieranie przeskakuje do liczby bajtów, które już ma. Inne wiersze na stderr, w tym ostrzeżenia, to tekst dla człowieka: program bierze wiersze, które dają się sparsować jako obiekty JSON, i pomija resztę.

Pytania i potwierdzenie

Polecenie, które zmienia maszynę, najpierw mówi, co zrobi, a potem pyta:

• Polecenie, które coś usuwa lub nadpisuje, najpierw mówi, co zniknie. Polecenie, które instaluje, najpierw mówi, co zainstaluje. agent stop najpierw mówi, co zakończy zatrzymanie agenta.
• --yes odpowiada „tak” na każde pytanie polecenia i wybiera wartość domyślną tam, gdzie polecenie oferuje wybór.
• W terminalu pytanie ma wstępnie wybraną odpowiedź „Tak”, więc sam Enter kontynuuje. Trzy pytania mają wstępnie wybraną odpowiedź „Nie”, więc sam Enter niczego nie wymazuje ani nie usuwa: os flash przed wymazaniem nośnika, os flash przed zastąpieniem pliku z --output oraz agent remove.
• os reset prosi o wpisanie nazwy urządzenia, a os install o wpisanie nazwy hosta maszyny. Każda inna odpowiedź, także sam Enter, oznacza „nie”.
• Znaki wpisane przed pojawieniem się pytania są ignorowane. Na pytanie odpowiada się dopiero po przeczytaniu tego, co mówi polecenie.
• Esc oznacza „nie”: polecenie niczego nie zmienia i kończy się kodem wyjścia 4. Ctrl-C przy pytaniu nie daje żadnej odpowiedzi, nawet tej wstępnie wybranej: polecenie niczego nie zmienia i kończy się kodem wyjścia 130.

Pytanie wymaga terminala zarówno na stdin, jak i na stderr. Bez niego (potok, CI, skrypt cloud-init) polecenie nie czeka i nie zgaduje: kończy się kodem wyjścia 4 i informuje, że potwierdza się flagą --yes. To samo dotyczy --json, która o nic nie pyta. Dlatego skrypty podają --yes razem z --json.

--yes nigdy nie znosi odmowy. Gdy polecenie odmawia działania (kod wyjścia 3 lub nieudany test), żadna flaga nie sprawi, że będzie kontynuować. Strona każdego polecenia wymienia sytuacje, w których odmawia ono działania. Jedynym wyjątkiem jest dysk wewnętrzny, który os flash --allow-internal zapisuje, gdy wskazuje go --drive.

Przez --host pytania docierają do ciebie, gdy uruchamiasz polecenie w terminalu. Na kilku maszynach jednocześnie nikt nie jest pytany, więc polecenie, które zadaje pytanie, działa tam tylko z --yes (zobacz Zdalne maszyny przez SSH).

Uprawnienia roota

Polecenie, które zmienia system, wymaga roota. Bez roota kończy się kodem wyjścia 3 i informuje o tym. Samo nie wywołuje sudo; robi to tylko --host, na zdalnej maszynie. os flash podaje wtedy wiersz poleceń do wpisania, z sudo na początku.

Przez --host polecenie wymagające roota działa przez sudo na zdalnej maszynie, gdy konto SSH nie jest kontem root.

Sekrety

Żadne polecenie nie wypisuje sekretu: ani sekretu pliku .flock, ani hasła WiFi, ani hasła proxy, ani klucza licencyjnego. Dotyczy to stdout, stderr, --json i komunikatów o błędach.

Sekret nigdy nie jest wartością flagi tam, gdzie może go przenieść plik, ponieważ wiersze poleceń są widoczne w ps i w historii powłoki. Hasło proxy nie jest wyjątkiem:

• Adres URL proxy we fladze podaje użytkownika bez hasła: http://[email protected]:3128.
• Adres URL z hasłem, taki jak http://user:password@proxy:3128, to błędny wiersz poleceń (kod wyjścia 2). Jest odrzucany, zanim cokolwiek się uruchomi, a z --host zanim trafi na maszynę. Komunikat błędu go nie powtarza.
• Hasło pochodzi z --proxy-password-file: z pliku lub potoku (/dev/stdin) z jednym wierszem.
• Zmienne proxy ze środowiska, których agent install używa, gdy brakuje flag, mogą zawierać hasło: nie stoją w wierszu poleceń.

# Hasło z pliku
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
 
# Hasło przez potok
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt

Na urządzeniu skonfigurowanym przez agent install hasło proxy leży tam, gdzie odczyta je tylko root: w /etc/ironflock/proxy.env (tryb 0600). Drop-iny docker.service i ironflock-device-agent.service wskazują ten plik i nie zawierają żadnego ustawienia proxy, więc systemctl show pokazuje każdemu użytkownikowi nazwę pliku i nic z jego zawartości.

Przez --host plik .flock, plik z hasłem WiFi lub plik z hasłem proxy podany we fladze trafia na zdalną maszynę przez połączenie SSH, nigdy w wierszu poleceń (zobacz Zdalne maszyny przez SSH). Bazowy adres pobierania z danymi logowania kończy się kodem wyjścia 2, zanim nastąpi połączenie z jakąkolwiek maszyną.

Kody wyjścia

Błąd to jeden wiersz na stderr: Error: , a po nim komunikat. Po błędzie użycia następuje wiersz, który wskazuje --help do przeczytania. Z --json błąd jest wynikiem: stdout dostaje obiekt błędu, a stderr nie dostaje wiersza błędu. kind to jeden z rodzajów z tabeli.

{"error":{"kind":"precondition","message":"the agent is not installed on this machine"}}

Dwa polecenia zapisują swój wynik i mimo to kończą się kodem wyjścia 1. agent update robi tak, gdy agent pozostaje przy swojej wersji: wynik mówi dlaczego, a stderr dostaje wiersz Error:. doctor robi tak, gdy jakiś test się nie powiódł: wynik mówi który, a wiersz błędu nie następuje. Z --json żadne z nich nie zapisuje wtedy obiektu błędu: stdout zawiera wynik.

Z --help nieznane polecenie nie jest błędem: ironflock os nosuch --help wypisuje pomoc ironflock os z kodem wyjścia 0. Na kilku maszynach polecenie kończy się najgorszym kodem wyjścia spośród maszyn (zobacz Zdalne maszyny przez SSH).

Przerwania

Ctrl-C, SIGTERM i SIGHUP (gdy znika terminal lub sesja SSH) kończą większość poleceń natychmiast, jak każdy program, bez wiersza błędu; powłoka widzi 130 (143 po SIGTERM, 129 po SIGHUP). Niektóre kroki je obsługują:

• os flash podczas pobierania, zapisu lub ponownego odczytu obrazu oraz os update podczas pobierania i sprawdzania pakietu aktualizacji zatrzymują się na następnym bloku. Informują, co po sobie zostawiły, błędem rodzaju interrupted i kończą się kodem 130; os update niczego wtedy nie instaluje. Gdy os flash odczytało już ostatni blok, jego końcowe kroki dobiegają końca i polecenie kończy się kodem 0. Drugie Ctrl-C kończy proces natychmiast; z --output może zostać plik .part.
• agent logs --follow śledzi log aż do takiego sygnału, a potem kończy się kodem 0.
• agent update przestaje śledzić aktualizację z kodem 130; agent kontynuuje ją samodzielnie.
• os reset w trakcie zapisu swojego żądania wycofuje to żądanie, kończy się kodem 130, a urządzenie się nie restartuje.
• agent configure, gdy już zaczęło zmieniać maszynę, nie zatrzymuje się po utracie terminala lub sesji SSH. Ctrl-C i SIGTERM nadal kończą je natychmiast.
• os install zachowuje się inaczej przed swoim pytaniem i po nim; zobacz ironflock os install.

Kody wyjścia w skrypcie

Skrypt podaje --yes, aby polecenie nie zatrzymało się na pytaniu, --json, aby dostać wynik do odczytu, i sprawdza kod wyjścia:

#!/bin/sh
# Zleć agentowi samoaktualizację; zachowaj wynik JSON, pomiń postęp ze stderr.
result=$(sudo ironflock agent update --yes --json 2>/dev/null)
code=$?
case $code in
  0) echo "agent is current: $result" ;;
  1) echo "agent update failed: $result" ;;
  3) echo "agent update refused on this machine: $result" ;;
  *) echo "agent update ended with exit code $code: $result" ;;
esac

Przy kodzie wyjścia 0 $result zawiera wynik, którego outcome to updated lub current. Przy kodzie wyjścia 1 zawiera albo wynik, którego outcome i reason mówią, dlaczego agent pozostaje przy swojej wersji, albo obiekt błędu. Przy kodzie wyjścia 3 zawiera obiekt błędu.