Bayraklar, Çıktı ve Çıkış Kodları

Bu kurallar her ironflock komutu için geçerlidir ve bir betik bunlara güvenebilir. Her komutun sayfası yalnızca o komutun eklediklerini belirtir.

Bir komut satırı iki biçimden birine sahiptir:

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

Grup üründür: cihaz ajanı için agent, IronFlock Appliance için appliance, IronFlockOS için os. Bir fiil her grupta aynı anlama gelir. Makinenin bütünüyle ilgili komutların grubu yoktur. Fiil olmadan çalıştırılan ironflock ve ironflock <group> yardımlarını yazdırır. Sayfasında aksi belirtilmedikçe hiçbir komut konumsal bağımsız değişken almaz; geri kalan her şey bir bayraktır. login ve device ayrılmış adlardır: ayrılmış olduklarını söyler ve çıkış kodu 2 ile sona ererler.

Genel Bayraklar

Her komut bu bayrakları kabul eder. --help dışındaki hepsi komutun adından önce veya sonra gelebilir: ironflock --json version ile ironflock version --json aynıdır.

Sabit Adlı Bayraklar

Bir bayrak adı, o bayrağı kullanan her komutta aynı anlama gelir. -h dışında yalnızca -c ve -d kısa bayrak olarak vardır.

İndirme Tabanı ve Proxy

İndirme tabanı --download-base bayrağından, ardından IRONFLOCK_DL_BASE ortam değişkeninden gelir; ikisi de yoksa https://instance-registry.ironflock.com/dl olur. İkisi de olmadığında agent install, doctor, os install ve os update, buluttan önce cihazın .flock dosyasının belirttiği Appliance’ın indirme yansısını kullanır (IronFlock Appliance Cihazları).

Proxy bayraklardan, ardından HTTP_PROXY, HTTPS_PROXY ve NO_PROXY değişkenlerinden (veya küçük harfli biçimlerinden) gelir. agent configure bir istisnadır: cihazın proxy’sini yalnızca kendi bayraklarıyla değiştirir; komutun ortamı orada hiçbir şeyi değiştirmez. Bir proxy URL’si http://proxy.example.com:3128 biçimindedir; https:// ve socks5:// de çalışır, şeması olmayan bir URL ise http:// sayılır. Proxy oturum açma gerektirdiğinde URL, http://[email protected]:3128 örneğindeki gibi kullanıcıyı belirtir, parolayı ise --proxy-password-file verir (bkz. Gizli Bilgiler). Proxy arkasındaki cihazlar için bkz. Kurumsal Proxy Arkasında.

Çıktı ve JSON

stdout yalnızca sonucu taşır. Bu, bir kişi için kısa bir metin ya da --json ile tek satırda tam olarak bir JSON nesnesidir. --help de stdout’a gider. Tek istisna, sonucu günlüğün kendisi olan agent logs komutudur: --json ile günlüğün her satırı için bir JSON nesnesi yazar.

stderr geri kalan her şeyi taşır: ilerleme, bir komutun çalıştırdığı araçların çıktısı (apt, Docker yükleyicisi), uyarılar, sorular ve hatalar.

Böylece bir yönlendirme veya komut ikamesi yalnızca sonucu alır; sessizlik isteyen bir betik stderr’i yönlendirir:

# Sonuç metin olarak bir dosyada; ilerleme ve uyarılar yine terminalde görünür
ironflock status > result.txt
 
# Sonuç JSON olarak bir kabuk değişkeninde, stderr'deki mesajlar olmadan
result=$(ironflock status --json 2>/dev/null)

JSON’daki alan adları snake_case biçimindedir. Komut bir şeyi değiştirdiğinde sonuçta action alanı bulunur, örneğin "installed", "configured" veya "removed". Zamanla alanlar eklenir; bir ana sürüm içinde hiçbir alan yeniden adlandırılmaz veya kaldırılmaz. Bir sonucu okuyan program, bilmediği alanları yok sayar. Birkaç makinede --json bunun yerine makine başına bir satır yazar (bkz. SSH Üzerinden Uzak Makineler).

İlerleme

Uzun bir adım, ne kadar ilerlediğini stderr’de gösterir: terminalde bir çubukla, aksi hâlde her onda birde bir satırla. --json ile stdout yine tam olarak bir JSON nesnesi, yani sonucu alır; stderr ise ilerlemeyi olaylar olarak, satır başına bir JSON nesnesi şeklinde alır:

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

os install yeniden başlatmadan önce görüntü dosyasını iki kez okur: checking onun SHA-256 değerini imzalı katalogla karşılaştırır; preparing ise görüntüyü bir kez açarak IRONFLOCKOS bölümünü bulur, cihazın .flock dosyasını ve ağ ayarlarını bu bölüme koyar ve yazımın diske koyacaklarının sağlama toplamlarını hesaplar. Terminalde bunlar Checking ve Preparing olarak görünür.

Bir aşama başladığında (done 0’dır), tam sayı yüzde her değiştiğinde ve aşama tamamlandığında (done, total değerine eşittir) bir olay gelir. Kaldığı yerden devam eden bir indirme, elindeki bayt sayısına atlar. stderr’deki diğer satırlar, uyarılar da dahil, bir kişi için yazılmış metinlerdir: bir program JSON nesnesi olarak ayrıştırılabilen satırları alır ve geri kalanını atlar.

Sorular ve Onay

Makineyi değiştiren bir komut önce ne yapacağını söyler, sonra sorar:

• Bir şeyi kaldıran veya üzerine yazan bir komut önce neyin gideceğini söyler. Kurulum yapan bir komut önce neyi kuracağını söyler. agent stop önce ajanı durdurmanın neyi sona erdireceğini söyler.
• --yes, komutun her sorusunu evet ile yanıtlar ve komutun seçim sunduğu yerde varsayılanı alır.
• Terminalde bir soru “Yes” seçeneğini önceden seçer; böylece yalnızca Enter’a basmak devam ettirir. Üç soru “No” seçeneğini önceden seçer; böylece yalnızca Enter’a basmak hiçbir şeyi silmez ve kaldırmaz: os flash bir sürücüyü silmeden önce, os flash --output dosyasını değiştirmeden önce ve agent remove.
• os reset cihazın adını, os install ise makinenin ana bilgisayar adını yazmanızı ister. Başka herhangi bir yanıt, yalnızca Enter da dahil, hayır anlamına gelir.
• Bir soru görünmeden önce yazdıklarınız atılır. Bir soru, komutun söylediklerini okuduktan sonra yanıtlanır.
• Esc hayır yanıtı verir: komut hiçbir şeyi değiştirmez ve çıkış kodu 4 ile sona erer. Bir soruda Ctrl-C hiçbir yanıt vermez, önceden seçilmiş olanı bile: komut hiçbir şeyi değiştirmez ve çıkış kodu 130 ile sona erer.

Bir soru hem stdin hem de stderr üzerinde bir terminal gerektirir. Terminal yoksa (bir pipe, CI, bir cloud-init betiği) komut beklemez ve tahmin yürütmez: çıkış kodu 4 ile sona erer ve --yes ile onaylanabileceğini söyler. Hiçbir şey sormayan --json ile de aynısı geçerlidir. Bu nedenle betikler --yes bayrağını --json ile birlikte verir.

--yes bir reddi asla kaldırmaz. Bir komut reddettiğinde (çıkış kodu 3 veya başarısız bir denetim), hiçbir bayrak onu devam ettiremez. Her komutun sayfası neyi reddettiğini listeler. Tek istisna dahili bir disktir: --drive onu belirttiğinde os flash --allow-internal ona yazar.

--host üzerinden, komutu bir terminalde çalıştırdığınızda sorular size ulaşır. Aynı anda birkaç makinede kimseye soru sorulmaz; bu yüzden soru soran bir komut orada yalnızca --yes ile çalışır (bkz. SSH Üzerinden Uzak Makineler).

Root Yetkileri

Sistemi değiştiren bir komut root gerektirir. Root olmadan çıkış kodu 3 ile sona erer ve nedenini söyler. sudo komutunu kendisi çağırmaz; bunu yalnızca --host diğer makinede yapar. os flash bu durumda yazılacak komut satırını başında sudo ile belirtir.

--host üzerinden, root gerektiren bir komut, SSH kullanıcısı root değilse diğer makinede sudo aracılığıyla çalışır.

Gizli Bilgiler

Hiçbir komut gizli bir bilgiyi yazdırmaz: ne bir .flock dosyasındaki gizli bilgiyi, ne bir WiFi parolasını, ne bir proxy parolasını, ne de bir lisans anahtarını. Bu kural stdout, stderr, --json ve hata mesajları için geçerlidir.

Bir dosyanın taşıyabileceği yerlerde gizli bilgi asla bir bayrağın değeri olmaz, çünkü komut satırları ps çıktısında ve kabuk geçmişinde görünür. Proxy parolası da bir istisna değildir:

• Bir bayraktaki proxy URL’si kullanıcıyı parola olmadan belirtir: http://[email protected]:3128.
• http://user:password@proxy:3128 gibi parola içeren bir URL hatalı bir komut satırıdır (çıkış kodu 2). Herhangi bir şey çalışmadan önce, --host ile de makineye gitmeden önce reddedilir. Hata mesajı URL’yi tekrarlamaz.
• Parola --proxy-password-file bayrağından gelir: tek satırlık bir dosya veya bir pipe (/dev/stdin).
• agent install komutunun başvurduğu ortamdaki proxy değişkenleri parola taşıyabilir: bunlar bir komut satırında yer almaz.

# Parola bir dosyadan
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
 
# Parola bir pipe üzerinden
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt

agent install komutunun kurduğu bir cihazda proxy parolası yalnızca root’un okuyabildiği bir yerdedir: /etc/ironflock/proxy.env dosyasında (mod 0600). docker.service ve ironflock-device-agent.service için drop-in dosyaları bu dosyanın adını verir ve hiçbir proxy ayarı içermez; böylece systemctl show her kullanıcıya dosyanın adını söyler, içeriğinden ise hiçbir şey söylemez.

--host üzerinden, bir bayrakta belirtilen .flock dosyası, WiFi parola dosyası veya proxy parola dosyası hiçbir zaman bir komut satırında değil, SSH bağlantısı üzerinden diğer makineye gider (bkz. SSH Üzerinden Uzak Makineler). İçinde kullanıcı adı ve parola bulunan bir indirme tabanı, hiçbir makineye ulaşılmadan çıkış kodu 2 ile sona erer.

Çıkış Kodları

Bir hata, stderr’de Error: ve ardından mesajdan oluşan tek bir satırdır. Bir kullanım hatasının ardından okunacak --help komutunu belirten bir satır gelir. --json ile hata sonucun kendisidir: stdout bir hata nesnesi alır, stderr ise hata satırı almaz. kind, tablodaki türlerden biridir.

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

İki komut sonucunu yazar ve yine de çıkış kodu 1 ile sona erer. agent update, ajan kendi sürümünde kaldığında bunu yapar: sonuç nedenini söyler ve stderr Error: satırını alır. doctor, bir denetim başarısız olduğunda bunu yapar: sonuç hangi denetim olduğunu söyler ve ardından hata satırı gelmez. Bu durumlarda --json ile ikisi de hata nesnesi yazmaz: stdout’ta sonuç bulunur.

--help ile bilinmeyen bir komut hata değildir: ironflock os nosuch --help, ironflock os yardımını çıkış kodu 0 ile yazdırır. Birkaç makinede komut, makinelerin en kötü çıkış koduyla sona erer (bkz. SSH Üzerinden Uzak Makineler).

Kesmeler

Ctrl-C, SIGTERM ve SIGHUP (terminal veya SSH oturumu ortadan kalktığında) çoğu komutu, herhangi bir programı sonlandırdıkları gibi, hata satırı olmadan hemen sonlandırır; kabuk 130 görür (SIGTERM sonrasında 143, SIGHUP sonrasında 129). Bazı adımlar bu sinyalleri kendisi ele alır:

• os flash bir görüntüyü indirirken, yazarken veya geri okurken, os update de bir güncelleme paketini indirirken ve denetlerken bir sonraki blokta durur. Geride ne bıraktıklarını interrupted türünde bir hata olarak söyler ve 130 ile sona ererler; os update bu durumda hiçbir şey kurmaz. os flash son bloğu geri okuduktan sonra kapanış adımlarını tamamlar ve 0 ile sona erer. İkinci bir Ctrl-C süreci hemen sonlandırır; --output ile .part dosyası geride kalabilir.
• agent logs --follow böyle bir sinyale kadar günlüğü izler ve ardından 0 ile sona erer.
• agent update güncellemeyi izlemeyi 130 ile bırakır; ajan kendi başına devam eder.
• os reset, isteğini yazarken isteği geri alır, 130 ile sona erer ve cihaz yeniden başlamaz.
• agent configure, makineyi değiştirmeye başladıktan sonra kaybolan bir terminal veya SSH oturumu yüzünden artık durmaz. Ctrl-C ve SIGTERM onu yine hemen sonlandırır.
• os install sorusundan önce ve sonra farklı davranır; bkz. ironflock os install.

Betikte Çıkış Kodları

Bir betik, komutun sorusunda durmaması için --yes, okuyabileceği bir sonuç için --json verir ve çıkış kodunu denetler:

#!/bin/sh
# Ajanın kendini güncellemesini sağlayın; JSON sonucunu tutun, stderr'deki ilerlemeyi atın.
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

Çıkış kodu 0 ile $result, outcome değeri updated veya current olan sonucu tutar. Çıkış kodu 1 ile ya outcome ve reason değerleri ajanın neden kendi sürümünde kaldığını söyleyen sonucu ya da bir hata nesnesini tutar. Çıkış kodu 3 ile hata nesnesini tutar.