Dziś opowiemy sobie o ostatnim elemencie układanki, który pozwoli nam bezpiecznie wyruszyć w samodzielną podróż w CLI EuroAP i pokrewne platformy aplikacyjne – mowa o formacie poleceń. Może się to wydawać trywialne, ale dobre zrozumienie fundamentów pomaga czytać i edytować cudze skrypty oraz oszczędza mnóstwo czasu, energii i frustracji. Zatem do dzieła.
CLI, jak każde sensowne narzędzie, ma rzeczową pomoc. Uruchamia się ją jakże zaskakującym poleceniem help ;-) Jeśli interesuje nas instrukcja obsługi konkretnego polecenia, możemy ją zobaczyć, używając przełącznika --help np.: deploy --help.
W pomocy ogólnej dla CLI możemy przeczytać, że CLI ma dwa rodzaje poleceń – powłokopodobne oraz właściwe dla CLI. Te drugie nazywane są często operacjami i mają oczywisty, przejrzysty format:
[node-type=node-name (/node-type=node-name)*] : operation-name ['('[name=value [, name=value]*]')'] [{header (;header)*}]
Przeanalizujmy ten ciąg znaków. Najważniejszym elementem jest : operation-name , gdyż tylko on nie jest opcjonalny, tylko on nie jest ujęty w „[ ]”.
Zatem najprostsze pod względem składni polecenie będzie wyglądało np. tak :read-resource albo tak :whoami.
Węzły
Każda operacja jest wykonywane na węźle, który możemy zdefiniować przy pomocy składni: [node-type=node-name (/node-type=node-name)*] . Jak widać, „[ ]” to element opcjonalny, co oznacza, że nie musimy podawać węzła w ogóle.
Domyślnie, gdy nie podamy ścieżki, to polecenie jest wykonywane na bieżącym węźle, ponieważ CLI jest kontekstowe. Dobrze widać to na przykładzie:
[[email protected]:9990 subsystem=undertow] pwd /subsystem=undertow [[email protected]:9990 subsystem=undertow] :read-resource { "outcome" => "success", "result" => { "default-security-domain" => "other", "default-server" => "default-server", "default-servlet-container" => "default", "default-virtual-host" => "default-host", "instance-id" => expression "${jboss.node.name}", "statistics-enabled" => false, "application-security-domain" => undefined, "buffer-cache" => {"default" => undefined}, "configuration" => { "filter" => undefined, "handler" => undefined }, "server" => {"default-server" => undefined}, "servlet-container" => {"default" => undefined} } }
[[email protected]:9990 server=default-server] pwd /subsystem=undertow/server=default-server [[email protected]:9990 server=default-server] :read-resource { "outcome" => "success", "result" => { "default-host" => "default-host", "servlet-container" => "default", "ajp-listener" => undefined, "host" => {"default-host" => undefined}, "http-listener" => {"default" => undefined}, "https-listener" => {"https" => undefined} } }
Powyższe polecenia możemy też wykonać jawnie, definiując adres węzła, na którym chcemy wykonać polecenie. Wówczas wyglądałyby one tak:
/subsystem=undertow:read-resource
/subsystem=undertow/server=default-server:read-resource
Aby znaleźć interesujący nas adres, możemy używać klawisza Tab do skutku, albo też przyjrzeć się plikom konfiguracyjnym „standalone.xml”, „domain.xml” czy „host.xml”.
Najczęściej używanymi węzłami są:
- /deployment=NAZWA_WDROŻENIA
- /socket-binding-group=NAZWA_GRUPY
- /interface=NAZWA_INTERFEJSU
oraz dla trybu standalone:
- /subsystem=NAZWA_PODSYSTEMU
i dla trybu domain:
- /profile=NAZWA_PROFILU/subsystem=NAZWA_PODSYSTEMU
- /host=NAZWA_HOSTU.
Naturalnie „/” przed każdym z wyżej wymienionych węzłów oznacza, że posługujemy się adresem bezwzględnym. Węzły można też adresować względnie.
Parametry
Kolejnym opcjonalnym elementem operacji w CLI jest ['('[name=value [, name=value]*]')']. Zatem polecenie może (nie musi) przyjmować argumenty w formie „nazwa=wartość”. Może przyjąć jeden argument albo dowolnie wiele, rozdzielając je przecinkami np.:
:read-resource(recursive=true) :read-resource(recursive=true,recursive-depth=3, include-aliases=true, include-runtime=true)
Dla kogo opcjonalne, dla tego opcjonalne. Niektóre polecenia bez parametrów po prostu nie mają sensu. Jeśli zapomnimy odpowiednich parametrów, dostaniemy stosowną informację zwrotną – „dany argument nie może być pusty”. Na przykład:
[[email protected]:9990 /] /profile=default:clone { "outcome" => "failed", "failure-description" => {"domain-failure-description" => "WFLYCTL0155: 'to-profile' may not be null"}, "rolled-back" => true }
Oczywiście nie musimy czekać, aż CLI zwróci nam uwagę. Za pomocą polecenia :read-operation-description możemy szybko sprawdzić, jakie parametry są niezbędne.
[[email protected]:9990 /] /profile=default:read-operation-description(name=clone) { "outcome" => "success", "result" => { "operation-name" => "clone", "description" => "Clones this profile to a new one. The clone is a copy of all this profile's configuration and subsystems.", "request-properties" => {"to-profile" => { "type" => STRING, "description" => "The name of the new profile to be created.", "expressions-allowed" => false, "required" => true, "nillable" => false, "min-length" => 1L, "max-length" => 2147483647L }}, "reply-properties" => {}, "access-constraints" => {"sensitive" => {"read-whole-config" => {"type" => "core"}}}, "read-only" => false, "runtime-only" => false } }
Parametry często przyjmują wartość prawda lub fałsz. Możemy uprościć ich zapis: „parametr=true” można zapisać po prostu jako „parametr”, a „parametr=false” jako „!parametr”.
Poniższe pary operacji są równoważne:
:read-resource(include-defaults=false) :read-resource(!include-defaults)
:read-resource(include-runtime=true) :read-resource(include-runtime)
Nagłówki
Ostatnim elementem w poleceniu CLI są nagłówki (ang. headers) [{header (;header)*}]. Nagłówki służą do kontrolowania niektórych aspektów wykonania operacji.
Dostępne są następujące nagłówki:
- allow-resource-service-restart – domyślnie ustawiony na fałsz. Niektóre operacje wymagają restartu serwisów. Ten nagłówek sprawia, że restart jest wykonywany od razu, automatycznie. Niestety nie wszystkie zasoby wspierają tę opcję;
- blocking-timeout – pozwala zdefiniować maksymalny czas, przez który pozwalamy operacji blokować zasoby. Nie jest to maksymalny czas trwania operacji, gdyż operacja może wielokrotnie blokować różne zasoby w trakcie swojego wykonywania. Ten nagłówek mówi, że na tym konkretnym etapie wykonywania operacja nie może blokować zasobu dłużej niż domyślnie 300 sekund, czyli 5 minut. Zatem jeśli mamy błąd timeoutu przy domyślnych ustawieniach, to coś poszło naprawdę źle;
- roles – pozwala sterować rolami w mechanizmie Role-Based Access Control. Domyślnie operacje są wykonywane z rolami przypisanymi do użytkownika, który wywołuje operacje. Nagłówek „roles” pozwala zmniejszyć przyznawane pozwolenia.
[[email protected]:9990 /] :whoami(verbose=true) { "outcome" => "success", "result" => { "identity" => { "username" => "$local", "realm" => "ManagementRealm" }, "mapped-roles" => ["SuperUser"] } } [[email protected]:9990 /] :whoami(verbose=true){roles=[Maintainer,Deployer]} { "outcome" => "success", "result" => { "identity" => { "username" => "$local", "realm" => "ManagementRealm" }, "mapped-roles" => [ "Maintainer", "Deployer" ] }
- rollback-on-runtime-failure – domyślne ustawienie na prawdę (=true) sprawia, że jeśli zmiany konfiguracji w runtime się nie powiodą, to zostanie przywrócona trwała (ang. persistent) konfiguracja. Inaczej mówiąc, jeśli zmieniamy coś w CLI, to od razu jest to zapisywane do odpowiednich plików konfiguracyjnych (można to sprawdzić, wywołując polecenia zmieniające konfigurację i weryfikując timestampy plików konfiguracyjnych). Jednak jeśli operacja zmiany się nie powiedzie, to domyślnie CLI nie zapisze tego do pliku. Co więcej, wczyta zawartość pliku sprzed naszej nieudanej próby zmiany. Takie zachowanie chroni nas przed uszkodzeniem konfiguracji, ale jeżeli chcemy, możemy tę ochronę wyłączyć.
- rollout – pozwala zdefiniować plan rollout dla danej operacji. Używany w trybie domain, szczególnie przydatny, gdy zmiana dotyczy wielu serwerów i musi być aplikowana w odpowiedniej kolejności itp. Ciekawy temat, który jeszcze zgłębimy w naszym kompendium.
Nagłówki, w przeciwieństwie do parametrów, nie wspierają skróconego zapisu wartości logicznych.
[[email protected]:9990 /] /subsystem=datasources/data-source=ExampleDS:enable{rollback-on-runtime-failure} Header 'rollback-on-runtime-failure' is not complete.
Zakończenie
Znamy już podstawowe koncepcje CLI EuroAP i pokrewnych serwerów aplikacyjnych, takich jak Red Hat® JBoss® Enterprise Application Platform oraz format poleceń. Możemy bez trudu odkrywać Command Line Interface na własną rękę, do czego gorąco zachęcamy. Równie gorąco polecamy kolejne wpisy w ramach naszego kompendium ;)
Command Line Interface w Application Platform – kompendium cz. I.
Command Line Interface w Application Platform – kompendium cz. II.
Command Line Interface w Application Platform – kompendium cz. III. - ten materiał
Chcesz być na bieżąco? Obserwuj nasz profil w serwisie LinkedIn.