SSH Üzerinden Uzak Makineler

--host, bir ironflock komutunu bu makine yerine SSH üzerinden başka bir makinede çalıştırır. Bununla cihazları dizüstü bilgisayarınızdan (bu bir Mac de olabilir) yönetirsiniz; cihazlara ironflock kurmanız gerekmez. Birden fazla kez ya da bir hosts dosyasıyla verildiğinde komutu aynı anda birçok makinede çalıştırır.

ironflock --host [user@]machine <command> [flags]
ironflock --host [user@]machine --host [user@]machine ... <command> [flags]
ironflock --hosts <file> [--parallel <n>] <command> [flags]

completion dışındaki her komut bu şekilde başka bir makinede çalışır. --host, --hosts ve --parallel genel bayraklardır: komutun adından önce veya sonra gelebilirler.

Tek Makine

--host [user@]machine, aynı komutu aynı bayraklarla o makinede çalıştırır. Komutun yazdırdıkları olduğu gibi geri gelir, stdout stdout’a, stderr stderr’e; çıkış kodu da aynen geri gelir.

$ ironflock --host pi@device-17 version
ironflock 2.0.2 linux/arm64
$ ironflock --host pi@device-17 agent remove --yes --json 2>/dev/null
{"action":"removed","removed":[...]}

Diğer Makinenin Gereksinimleri

• amd64, arm64 veya 32 bit ARM (v5 ile v7 arası) üzerinde Linux. Başka bir sistem çıkış kodu 3 ile sona erer.
• Komut çalıştıran bir SSH sunucusu. scp veya SFTP gerekmez.
• Bir POSIX oturum kabuğu: sh, bash, dash veya zsh. csh, tcsh ve fish, çıkış kodu 3 ve bunu belirten bir mesajla sona erer.
• root olarak oturum açma veya sudo, root gerektiren komutlar için (bkz. Diğer Makinede Root).

Makinede ironflock kurulu olması gerekmez: her çalıştırma kendi ikili dosyasını getirir.

SSH Ayarları

--host bu makinenin ssh aracını kullanır; böylece ~/.ssh/config dosyanız, anahtarlarınız, SSH ajanı ve atlama sunucuları (jump host) ssh ile olduğu gibi çalışır. Komutun ihtiyaç duymadığı şeyleri kapatır: ajan ve X11 yönlendirmesi, port yönlendirmeleri, RemoteCommand ve LocalCommand.

--host yalnızca [user@]machine alır, başka bir şey almaz. Port veya diğer seçenekler ~/.ssh/config dosyasına yazılır:

Host device-*
    User pi
    Port 2222
    StrictHostKeyChecking accept-new

Bu ayarla ironflock --host device-17 status, 2222 portunda pi olarak oturum açar ve ssh, henüz tanımadığı bir cihazın ana bilgisayar anahtarını kabul eder. - ile başlayan bir --host değeri reddedilir; harfler, rakamlar, ., _, - ve bir IPv6 adresindeki : ve % dışında karakter içeren bir değer de reddedilir.

Kontrol soketinin yolu yeterince kısa olduğunda tüm çalıştırmaya tek bir SSH bağlantısı hizmet eder; soket geçici klasörün altında, olmazsa /tmp altında oluşturulur. Bu durumda ssh parolayı bir kez sorar. Aksi hâlde çalıştırmanın her adımı kendi bağlantısını açar ve ssh her biri için yeniden sorar.

ironflock agent install veya IronFlockOS tarafından kurulan bir cihazda proje sahibi için bir SSH kullanıcısı bulunur; bu kullanıcı cihazın .flock dosyasındaki anahtarla oturum açar. SSH Erişimi sayfası kullanıcı adını ve anahtarın dosyadan nasıl çıkarılacağını gösterir.

Makinede Neler Olur

1. İkili dosya. Makine aynı platforma sahipse burada çalışan ikili dosyayı alır. Aksi hâlde ironflock, makinenin platformu için ikili dosyayı <download base>/cli/<os>/<arch>/<version>/ironflock adresinden indirir ve kullanmadan önce burada denetler: imzasını (.asc) bu ikili dosyanın taşıdığı IronFlock sürüm anahtarına göre, derleme bilgilerini de ironflock programını, makinenin platformunu ve bu ikili dosyayla aynı kaynak revizyonunu belirtip belirtmediğine göre. İndirilen dosya önbellek klasörünüzde (Linux’ta ~/.cache/ironflock, Mac’te ~/Library/Caches/ironflock) saklanır ve her kullanımda yeniden denetlenir.
2. Klasör. İkili dosya, yalnızca SSH kullanıcısının okuyabildiği yeni bir klasöre (mktemp -d) gider: makinede ${TMPDIR:-/tmp} altına ya da geçici klasörde bir program çalışamıyorsa (noexec ile bağlanmış bir dosya sistemi) SSH kullanıcısının ana dizini altına. Program ikisinde de çalışamıyorsa komut çıkış kodu 3 ile sona erer ve ikisini de belirtir. Makine, klasörden bir şey çalıştırmadan önce klasörün ve ikili dosyanın SSH kullanıcısına ait olduğunu ve sembolik bağlantı olmadığını, ikili dosyanın da beklenen sürüm ve platformda olduğunu denetler.
3. Dosyalar. Komutun bayraklarında belirtilen dosyalar da gönderilir (bkz. Bayraklarda Belirtilen Dosyalar).
4. Komut. SSH kullanıcısı olarak veya sudo aracılığıyla çalışır (bkz. Diğer Makinede Root).
5. Temizlik. Komut sona erdiğinde makine, ikili dosyanın ve kopyaların bulunduğu klasörü kaldırır: bir hatadan sonra, kopan bir bağlantıdan sonra ve HUP, INT, QUIT, TERM, PIPE, USR1 ve USR2 sinyallerinden sonra da.

--host, agent install sonrasında da makinede hiçbir ironflock bırakmaz. Buradan --host ile devam edin ya da ironflock aracını, bağımsız değişken verilmediğinde yalnızca kurulum yapan kurulum satırıyla makineye kurun. --host üzerinden self-update, çalıştırmanın ikili dosyasını değil, makinenin o /usr/local/bin/ironflock dosyasını günceller (ironflock self-update).

Makinede iki durumda bir ironflock.* klasörü kalır:

• Komut çalışırken makinede bir güç kesintisi veya kill -9 olduğunda. Klasör ikili dosyayı ve kopyaları içerir.
• Bağlantı, kopyalamadan sonra ve komut başlamadan önce koptuğunda ya da çalıştırma, komutu başlatan adım bağlanırken burada kesildiğinde. Klasör ikili dosyayı, komutu bir terminalde çalıştırdıysanız kopyaları da içerir.

Bir .flock dosyasının kopyası cihazın gizli bilgisini, bir WiFi parola dosyasının kopyası WiFi parolasını, bir proxy parola dosyasının kopyası proxy parolasını içerir. Bunları yalnızca SSH kullanıcısı ve root okuyabilir. Böyle bir klasörü elle kaldırın.

Bayraklarda Belirtilen Dosyalar

Her dosya burada okunur ve göreli bir yol bu makinenin çalışma klasörüne göre çözülür. Bir WiFi veya proxy parola dosyası bir pipe (/dev/stdin) olabilir; pipe bir kez okunur. İçerik, SSH bağlantısının standart girdisi üzerinden makineye gider. Ne bir dosya ne de boyutu bir komut satırında yer alır: ne burada ne de her kullanıcının komut satırlarını okuyabildiği makinede. Makine her boyutu komutun kabul ettiği en büyük boyuta göre, ardından da tamamının gelip gelmediğini denetler.

Makinede kopya <folder>/1/device.flock olur: çalıştırma klasörünün içinde kendine ait bir klasörde (mod 0700), buradaki adıyla ve mod 0600 ile. Oradaki komut bu yolu alır, örneğin --config=/tmp/ironflock.k3Xf9QpL2m/1/device.flock; böylece dosyanın içeriğiyle ilgili bir hata kopyayı belirtir.

Şunlar komutu bu makinede sonlandırır:

• Çıkış kodu 1 — normal dosya olmayan bir dosya (bir WiFi veya proxy parola dosyası bir pipe da olabilir) ya da komutun kabul ettiğinden büyük bir dosya: .flock dosyası için 5 MiB, WiFi veya proxy parola dosyası için 4096 bayt.
• Çıkış kodu 2 — kontrol karakteri içeren bir dosya adı.
• Çıkış kodu 2 — os flash komutunun --image-file ve --output bayrakları. --host makineye hiçbir görüntü kopyalamaz ve geri hiçbir dosya getirmez. Bu komutu burada --host olmadan ya da makinenin kendisinde çalıştırın. --image-file olmadan makine görüntüyü kendisi indirir.

Diğer Makinede Root

• Root gerektiren bir komut, SSH kullanıcısı root değilse sudo aracılığıyla çalışır. Parola ve terminal olmadan çalışan bir sudo her yerde işe yarar.
• version, os images ve os drives SSH kullanıcısı olarak çalışır.
• status ve doctor root ile daha fazlasını okur. SSH kullanıcısı root olduğunda ya da sudo komutunu parola ve terminal olmadan kullanabildiğinde root olarak çalışırlar. Aksi hâlde soru sormadan SSH kullanıcısı olarak çalışırlar ve ipuçları komutu --host root@machine ile belirtir.
• agent logs, root’a ait bir dosyayı okur ve sudo aracılığıyla çalışır.
• sudo parola sorduğunda veya yapılandırması bir terminal istediğinde (requiretty), makinede bir terminal gerekir. Bunun için de burada stdin, stdout ve stderr üzerinde bir terminal gerekir. Terminal yoksa komut, hiçbir şey kopyalanmadan çıkış kodu 3 ile sona erer. Bu durumda root olarak oturum açın, SSH kullanıcısının sudo komutunu parola ve terminal olmadan kullanmasına izin verin ya da komutu bir terminalde yönlendirme olmadan çalıştırın.
• Komut çalışmak üzereyken reddeden bir sudo da çıkış kodu 3 ile sona erer.

Oradaki komut sonraki adım olarak bir komut önerdiğinde bu, bu taraf için sudo olmadan yazılmış bir komuttur, çünkü --host root yetkisini kendisi alır: ironflock --host pi@device-17 agent start.

Terminal, Sorular ve Çıktı

• Burada bir terminal varsa komut makinede de bir terminal alır; böylece sorularını sorabilir. Bu durumda stdout ve stderr birlikte, terminalinize geri gelir.
• Burada terminal yoksa (bir pipe, bir programa giden --json, CI) stdout ve stderr ayrı kalır ve komut hiçbir şey sormaz: --yes onaylar. SSH kullanıcısının makinedeki dosyalarının yazdırdıkları, örneğin ekrana metin basan bir .bashrc, stdout’tan atılır; böylece stdout yalnızca komutun sonucunu taşır.
• --yes, --json ve komutun bayrakları da iletilir. İndirme tabanı --download-base olarak iletilir: bayrak ya da bu makinenin IRONFLOCK_DL_BASE değişkeni. Kullanıcı adı ve parola içeren bir indirme tabanı (https://user:[email protected]/dl), hiçbir makineye ulaşılmadan çıkış kodu 2 ile sona erer, çünkü makinede oradaki her kullanıcının okuyabildiği bir komut satırında yer alırdı.
• --help, help, komutu verilmemiş bir grup ve completion burada yanıtlanır: yazdırdıkları her makinede aynıdır.
• Makinenin komut çalışmadan önce stdout’a gönderdikleri (yanıtları ve SSH kullanıcısının dosyalarının metni) en fazla 64 KiB okunur. Daha fazlası, komut orada çalışmadan çalıştırmayı çıkış kodu 1 ile sonlandırır.

Ctrl-C ve Kopan Bağlantılar

Buradaki Ctrl-C, oradaki komuta kendi terminalindeki bir Ctrl-C gibi ulaşır; kopan bir bağlantı da burada terminal olsun ya da olmasın ona hat kapanması (hangup) olarak ulaşır. Ctrl-C’den sonra --host, makinenin oradaki komutun sona erdiğini çıkış koduyla (Ctrl-C sonlandırdıysa 130) birlikte bildirmesi için 15 saniyeye kadar bekler. Makine bunu zamanında bildirmezse ya da bağlantı önce sona ererse --host 130 ile sona erer ve komutun orada hâlâ çalışıyor olabileceğini söyler. Ctrl-C geldiğinde komutu henüz başlamamış bir çalıştırma, komutu başlatmaz.

--host üzerinden os install komutunun kendi kuralları vardır: sorusu yanıtlandıktan sonra kopan bir bağlantı onu artık durdurmaz ve komut burada makinenin IronFlockOS olarak geri gelmesini bekler; bkz. ironflock os install.

Çıkış Kodları ve Hatalar

Çıkış kodları komutun kendi çıkış kodlarıdır (Çıkış Kodları). --host şunları ekler:

--host kendisi başarısız olduğunda bu, diğerleri gibi bir hatadır: stderr’de bir Error: satırı ya da --json ile stdout’ta hata nesnesi. Tek istisna: komutun çıktısı zaten geldiyse sonuç o çıktıdır ve hata, --json ile de, yalnızca stderr’deki Error: satırıdır.

Birkaç Makine

Birden fazla kez verilen --host veya --hosts <file>, komutu her makinede, tek bir --host ile olduğu gibi çalıştırır. Önce --host makineleri, sonra dosyadakiler gelir. İçinde tek bir makine bulunan bir hosts dosyası da birkaç makine gibi çalışır.

$ ironflock --host pi@vm1 --host pi@vm2 --host pi@vm3 status
pi@vm2: Agent:         installed in /opt/ironflock/device-agent
pi@vm2:   Version:     1.6.9
pi@vm2:   Service:     running (ironflock-device-agent.service)
pi@vm3: ssh: connect to host vm3 port 22: Connection timed out
pi@vm3: Error: the SSH connection to pi@vm3 failed
pi@vm1: Agent:         installed in /opt/ironflock/device-agent
...
Summary of "status" on 3 machines, exit code 255: 2 done, 1 ssh.
  pi@vm1  done
  pi@vm2  done
  pi@vm3  255 ssh: the SSH connection to pi@vm3 failed (ssh: connect to host vm3 port 22: Connection timed out)

Hosts Dosyası

Dosya her satırda bir [user@]machine belirtir. # bir yorum başlatır ve yorum satır sonuna kadar sürer; boş satırlar atlanır. Dosya --hosts <(...) gibi bir pipe da olabilir ve en fazla 1 MiB tutar.

# Paketleme hattı 3
pi@device-17
pi@device-18
pi@device-19   # the spare unit

# Dosyadaki her makinenin durumunu, aynı anda 20 makinede gösterin
ironflock --hosts line3.txt --parallel 20 status
 
# Dosyadaki her makinede ajanı güncelleyin; agent update soru sorar, bu yüzden --yes gerekir
ironflock --hosts line3.txt agent update --yes
 
# Bir sahadaki cihazlara tek bir proxy hesabı verin; parola bir dosyadan gelir
ironflock --hosts site-a.txt agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt --yes

Şunlar, hiçbir şey çalışmadan çıkış kodu 2 ile sona erer ve hata, dosyayı ve satırı belirtir:

• birden fazla sözcük içeren bir satır;
• --host bayrağının reddedeceği bir makine;
• iki kez belirtilen bir makine. İki farklı kullanıcıyla belirtilen aynı makine de iki kez sayılır, çünkü komut o makinede aynı anda iki kez çalışırdı. Bir makinenin adresi ve adı aynı makine olarak tanınmaz.

Paralel Çalıştırmalar

Aynı anda en fazla --parallel kadar makine çalışır: bayrak olmadan 10, 1 ile 100 arası. Makineler verildikleri sırayla başlar; biri bittiğinde sıradaki başlar. Birkaç makine olmadan --parallel çıkış kodu 2 ile sona erer.

Sorusuz SSH

Hiçbir makine terminal almaz ve ssh hiçbir şey sormaz (BatchMode=yes). Şunlar o makinede çıkış kodu 255 ve ssh aracının kendi mesajıyla başarısız olur, diğer makineler çalışmaya devam eder:

• parola isteyen bir oturum açma;
• parolası SSH ajanında bulunmayan bir anahtar;
• ssh aracının henüz tanımadığı bir ana bilgisayar anahtarı.

Yeni bir ana bilgisayar anahtarını kabul etmek için bir kez ssh ile bağlanın ya da yukarıdaki örnekte olduğu gibi bu makineler için ~/.ssh/config dosyasında StrictHostKeyChecking accept-new ayarlayın. ssh, 30 saniye sonra bağlanmaktan vazgeçer (~/.ssh/config ne derse desin ConnectTimeout=30); böylece kapalı bir makine o süreden sonra bildirilir. Orada parola veya terminal isteyen bir sudo, o makinede çıkış kodu 3 ile sona erer; status ve doctor bu durumda SSH kullanıcısı olarak çalışır.

Birkaç Makinenin Çıktısı

• Bir makinenin yazdığı her satır bütün olarak, başında <host>: ile gelir: makinenin stdout’u stdout’a, stderr’i stderr’e. Makinelerin satırları geldikleri sırayla karışır.
• Satır sonu karakteri olmayan son satıra bir satır sonu eklenir. 64 KiB’tan uzun bir satır, her birinin başında makine adı bulunan 64 KiB’lık parçalar hâlinde gelir.
• Sekme dışındaki kontrol karakterleri, hiçbir makine imleci hareket ettiremesin veya başka bir makinenin satırının üzerine yazamasın diye satırlarda ve özette kaçış dizisi olarak (\x1b, \r) gelir. Satır sonundaki bir satır başı karakteri atılır.
• Burada başarısız olan bir çalıştırma, --host tek bir makine için nasıl yazıyorsa öyle, başında makine adı olan Error: satırını ekler.
• Sonunda stderr bir özet alır: çıkış kodu ve kaç makinenin nasıl sona erdiği, ardından verilen sırayla her makine için bir satır. Satır done der ya da çıkış kodunu, türünü ve nedenini söyler: buradaki hata (255 için ssh aracının kendi mesajıyla) veya komutun Error: satırı. Ctrl-C’den sonra komutunun sona erdiğini onaylamayan bir makine interrupted, may still run olur.

Birkaç Makinenin Çıkış Kodu

Komut, makinelerin en kötü çıkış koduyla sona erer: her makine 0 ile sona erdiğinde 0. Aksi hâlde en kötüsünden başlayarak:

1. 130 — burada veya bir makinede kesildi.
2. 1 — komut bir makinede başarısız oldu ve orada hangi kodla sona ermiş olursa olsun makineyi yarı değişmiş bırakmış olabilir.
3. 255 — bir makineye ulaşılamadı ya da bağlantı koptu.
4. 3 — bir makine komutun gerektirdiği durumda değildi ya da komutu çalıştıramıyor.
5. 4 — bir soru hayır ile yanıtlandı.

Çıkış kodu 2, her komutta olduğu gibi burada da hatalı bir komut satırı anlamına gelir.

JSON Satırları

--json ile stdout, her makine için komutu sona erdiğinde, bitiş sırasına göre bir satır alır ve başka hiçbir şey almaz. Bir program satırları geldikçe okur.

{"host":"pi@vm1","state":"done","exit_code":0,"result":{...}}

stderr makinelerin satırlarını, bunların arasında bir komutun --json ile de yazdığı kendi Error: satırını (agent update) ve özeti içerir. Buradaki çalıştırmaların hataları yalnızca stdout’taki satırlarda bulunur.

# status komutunun 0 ile sona ermediği makineler
ironflock --hosts line3.txt status --json 2>/dev/null | jq -r 'select(.state != "done") | .host'

Birkaç Makinede Ctrl-C

Ctrl-C, SIGTERM veya SIGHUP, çalıştırmaları tek bir makinedeki çalıştırmayı sonlandırdığı gibi sonlandırır: oradaki her komut sinyali alır ve her makinenin, komutunun sona erdiğini onaylamak için 15 saniyesi vardır. Onaylamayan bir makine may_still_run olur. Sırası gelmemiş makineler hiçbir şey çalıştırmaz. Özet bunları not started olarak listeler ve komut 130 ile sona erer.

Hangi Komutlar Birkaç Makinede Çalışır

Bu makinedeki bir dosyayı belirten bir bayrak birkaç makineyle reddedilir, çünkü dosya her makineye giderdi: doctor ve agent configure komutlarının -c bayrağı tek bir cihazı belirtir. İstisna, bir sahanın makineleri için tek bir proxy hesabı sağlayan agent configure komutunun --proxy-password-file bayrağıdır.

Birkaç makinede çalışmayan bir komut satırı, hosts dosyası okunmadan ve hiçbir makineye ulaşılmadan önce çıkış kodu 2 ile sona erer ve nedenini söyler.