Přejít na obsah
Flexideo
Skip to main content

Požadavek shell

Účel a dopady​

Spustí příkaz v shellu operačního systému serveru (command), nebo – je-li uveden id místo command – vyzvedne výsledek dříve spuštěného asynchronního příkazu.

Dostupnost, kontext, oprávnění apod.​

  • Vyžaduje r_admin.
  • Spuštění nového příkazu je navíc omezeno konfigurovaným seznamem povolených příkazů serveru. Příkaz, který neodpovídá žádnému nakonfigurovanému vzoru, je zamítnut jako nepovolený; výjimkou jsou interní systémové kontexty bez userid a vývojové sestavení bez nakonfigurovaných shellů.
  • Podléhá standardnímu transakčnímu zpracování obálky <request>.

XML požadavek (syntax + popis)​

  <request>
   <shell
    id="{number}"
    valid="{bool}"
    codepage="{string}"
    encode="hex|base64|url|xml|json|raw"
    exit-code="{number}"
    command="{string}"
    call="sync|async|detach"
    join-output="{bool}"
    no-output="{bool}"
    survive="{bool}"
    timeout="{number}"
    retrieve-timeout="{number}"
    out-buffer-size="{number}"
    err-buffer-size="{number}"
    input-encoding="hex|base64|xml|url|json"
    >
    {vstupní data pro standardní vstup programu}
   </shell>
  </request>

Parametry a pravidla (atributy, potomci)​

Požadavek má dva režimy, rozlišené přítomností id:

Režim vyzvednutí výsledku (id uveden)​

  • id - Identifikátor dříve spuštěného asynchronního příkazu. (typ: number; povinný v tomto režimu)
  • valid - Je-li "false", výsledek se po vyzvednutí ponechá k dalšímu dotazu; jinak (výchozí) se považuje za vyzvednutý. (typ: bool; nepovinný) – v dosavadní dokumentaci zcela chyběl.
  • codepage, encode, exit-code - Lze dodatečně přenastavit i při pouhém vyzvednutí výsledku (ovlivní, jak se výsledek zakóduje do odpovědi). (nepovinné)

Režim spuštění příkazu (command uveden)​

  • command - Příkaz včetně případných parametrů; prázdný nebo nepovolený (viz oprávnění výše) → chyba. (typ: string; povinný)
  • call - sync (výchozí)|async|detach. (typ: enum; nepovinný)
  • join-output - Sloučit standardní a chybový výstup. (typ: bool; nepovinný; výchozí: false)
  • no-output - Nevracet standardní výstup. (typ: bool; nepovinný; výchozí: false)
  • survive - Přežije zastavení serveru (jen call="async"). (typ: bool; nepovinný; výchozí: false)
  • timeout - Max. doba běhu v sekundách. (typ: number; nepovinný; výchozí: 30) – dosavadní dokumentace uváděla výchozí 0 (nekonečno); ve skutečnosti je výchozí 30.
  • retrieve-timeout - Max. doba čekání na vyzvednutí výsledku u call="async". (typ: number; nepovinný)
  • out-buffer-size, err-buffer-size - Velikost bufferů pro čtení výstupů. (typ: number; nepovinné)
  • codepage - utf8|utf16|acp|oem|číslo kódové stránky. (typ: string; nepovinný)
  • encode - Kódování vrácených výstupů: hex|base64|url|xml|json; jiná/chybějící hodnota = raw (bez úpravy). (typ: enum; nepovinný; výchozí: raw)
  • exit-code - Návratový kód považovaný za úspěch. (typ: number; nepovinný)
  • input-encoding - Kódování obsahu (textu/potomků) posílaného na standardní vstup: rozpoznávané prefixy hex, base64, xml (XML escape dekódování), url (URL dekódování), json (převod z interního JSON-XML do JSON). (typ: string; nepovinný) – dosavadní dokumentace uváděla utf8/utf16/acp/číslo kódové stránky, tyto hodnoty však tento atribut nerozpoznává.

Potomek: obsah uzlu <shell> (prostý text nebo vnořené XML) se pošle jako standardní vstup spouštěného programu podle input-encoding.

Příklady požadavku​

(Zatím bez ověřeného příkladu.)

Zpracování a vedlejší účinky​

  • V call="detach" server nemá o programu žádnou informaci po jeho spuštění – nelze vyzvednout výstup ani aplikovat timeout.
  • V call="async" se vrací id, kterým lze později (tímto požadavkem s atributem id) vyzvednout výsledek; po retrieve-timeout je výsledek zapomenut.

XML odpověď (syntax + popis)​

  <response>
   <shell
    status="ok|fail|running|detached|killed|not-found|error"
    id="{number}"
    detail="{string}"
    >
    <output ... /> ?
    <error ... /> ?
   </shell>
  </response>

Příklady odpovědi​

(Zatím bez ověřeného příkladu.)

Chyby a reakce​

  • status="error" detail="Neplatne id" – v režimu vyzvednutí je id chybějící/neplatné/0.
  • status="not-found" id="{id}" – zadané id neodpovídá běžícímu ani dokončenému příkazu.
  • status="running" id="{id}" – příkaz v call="async" stále běží.
  • status="error" detail="Nepovoleny prikaz" – command je prázdný nebo neodpovídá konfigurovanému seznamu povolených příkazů.
  • Nedostatečné oprávnění má odpověď <shell status="error" detail="Nemate patricna opravneni"/>.

Související požadavky​