Ez a honlap / dokumentáció a crosh, A Chromium OS shell. Ha a CrOS eszközök most, akkor képesnek kell lennie arra, hogy indítson crosh ütő Ctrl + Alt + T. Ha nem a CrOS, akkor a legvalószínűbb, hogy nem fog semmit hasznos:).

csak futtassa ahelp – t, hogy információt kapjon az elérhető parancsokról, és többet megtudjon.

a lap kitöltésével gyorsan megtalálhatja a meglévő parancsokat.

Ez egy kaland!

A Chromium OS fejlesztői számára

Ez a szakasz A Chromium OS-en hackelő emberek számára készült, különösen akkor, ha módosítani/kiterjeszteni kell a crosh-t.

Biztonsági figyelmeztetés

kérjük, ne telepítsen új modulokat teljes biztonsági felülvizsgálat nélkül. Bármely bizonytalan kód, amelyet a crosh betölt, közvetlenül elérhető lesz az ellenőrzött módban lévő emberek számára. Ez egy egyszerű támadási vektor, amely tetszőleges kódot futtat, és összezavarja a felhasználó állapotát. Nem akarjuk aláásni a CrOS biztonságát!

Ha keres értékelők, nézd meg a ./ Tulajdonosok fájl.

ahol a fájlok élnek

Crosh áttelepítésre kerül a héjról a rozsdára. Crosh indul végrehajtó src / main. rs de a legtöbb parancsokat végre, mint a saját almodulja az egyik magas szintű modulok(például base vagy dev).

a főcrosh szkript tartalmazza a core crosh logic legacy implementációját, míg más régi funkciók modulkönyvtárakban élnek. A crosh legacy verziója a crosh.shformátumban van telepítve az eszközre.

Source Repos

a táblára jellemző vagy egy csomagra erősen jellemző moduloknak általában az adott táblával és/vagy csomaggal kell élniük. Az összes CrOS eszközön mindig elérhető funkciók esetén ezt a kódot ebben a repo-ban kell tartani.

ha nem biztos benne, csak kérdezze meg [email protected].

új parancsok hozzáadása

először határozza meg, hogy az új parancs milyen végrehajtási stratégiát fog használni. A stratégia kiválasztásakor segít tudni, hogy milyen jogosultságokra és jogosultságokra van szükség. A stratégia szem előtt tartásával nézze meg az alábbi példákat.

Command Design

a crosh shell ugyanabban a környezetben fut, mint a böngésző (ugyanaz a felhasználó / csoport, ugyanaz a Linux névterek stb…). Tehát minden olyan eszköz, amelyet crosh-ban futtat, vagy amelyet megpróbál megszerezni, hozzáférhetőnek kell lennie a chronos felhasználó számára.

azonban ritkán akarjuk, hogy a crosh ténylegesen végrehajtsa az eszközöket közvetlenül. Ehelyett hozzá kell adnia a D-Bus hívásokat a debugd démonhoz, és minden kérést el kell küldenie hozzá. Jobban tudjuk irányítani a hozzáférést a debugd-ben és lezárni a szerszámokat. Ezután az egyetlen logika, amely létezik crosh egy D-Bus IPC hívást, majd megjeleníti kimenetet e programok. A debugd megvitatása itt nem terjed ki, ezért nézd meg a debugd könyvtárat.

példák

példa implementációk:

• D-Bus method wrapper (debugd): base::verify_ro
  használja ezt, ha a D-Bus API már tervezett vagy crosh hiányzik a szükséges engedélyek vagy képességek.
• külső bináris wrapper: base:: ccd_pass
  használja ezt, ha már van egy parancssori eszköz, amely végrehajtja a parancsot, hogy működik, ha fut chronos a képességeit crosh.
• Rust: base-ban írt parancs::arc
  Ez a legalkalmasabb olyan esetekben, amikor nincs szükség extra képességekre, és nincs szükség külön parancssori eszközre.

az alábbiakban egy minta munkafolyamat szerepel egy új parancs írásához.

modul Setup

válasszon egy megfelelő modult a parancshoz. Dev módú parancsok esetén ez a dev, a legtöbb más parancs a base parancshoz tartozik. Ez a példa a base modult használja, de más esetekben is ugyanazokat a lépéseket kell alkalmazni.

ezután válasszon ki egy parancsnevet, hozzon létre egy almodult ezzel a névvel, majd regisztrálja azt a szülőmodullal. Ebben a példában a parancs verify_ro, tehát az új forrásfájl src/base/verify_ro.rs, és két sort kell hozzáadni a src/base/mod.rs:

először az almodulet importálni kell:

mod verify_ro;

második a regiszter funkciót (amelyet az alábbiakban kell létrehozni) a src/base/mod.rs:

most a src/base/verify_ro.rs forrásfájl készen áll a megírásra. Kezdje ezzel a minimális forrásfájllal, majd ellenőrizze, hogy a crosh cargo build:

use crate::dispatcher::Dispatcher;pub fn register(dispatcher: &mut Dispatcher) { dispatcher.register_command( Command::new( "verify_ro".to_string(), "TODO put usage here".to_string(), "TODO put description here".to_string(), ) .set_command_callback(Some(execute_verify_ro)), );}fn execute_verify_ro(_cmd: &Command, args: &Arguments) -> Result<(), dispatcher::Error> { unimplemented!();}

parancs végrehajtása

Ez feltételezi, hogy a fenti utasítások már befejeződtek.

mivel a privilegizált műveleteket nem tudja végrehajtani a Crosh (de debugd-ben vagy bárhol máshol kell végrehajtani), az alábbi példa különösen a D-buszra összpontosít, és feltételezi, hogy létezik egy meglévő D-Bus módszer, amelyet új Crosh parancsból kell hívni.

Megjegyezzük, hogy debugd D-Busz interfész már a Rozsda kötések generált dev-rozsda/system_api, így a kötések, valamint a D-Bus kapcsolat hozható azzal, hogy:

use dbus::blocking::Connection;use system_api::client::OrgChromiumDebugd;

Ha azt akarod, hogy keresse meg a forráskódot a generált kötések, futtatása után build_packages, vessen egy pillantást a következő útvonalat:

/build/${BOARD}/usr/lib/cros_rust_registry/registry/system_api-*/src/bindings/client/

Belső rész a parancs végrehajtását, a D-Bus-kapcsolat kell inicializálni. Ebben a példában blokkoló kapcsolatot használunk.

let connection = Connection::new_system().map_err(|err| { error!("ERROR: Failed to get D-Bus connection: {}", err); dispatcher::Error::CommandReturnedError})?;

A busz kapcsolat lehet használni, hogy egy felületet, hogy a kívánt szolgáltatást, amely debugd ebben az esetben:

let conn_path = connection.with_proxy( "org.chromium.debugd", "/org/chromium/debugd", DEFAULT_DBUS_TIMEOUT,);

A többi módszer hívás használ az a tény, hogy az importált tulajdonság system_api::client::OrgChromiumDebugd végrehajtása a conn_path tehát a tagállamok funkciók térkép D-Bus módszerek is lehet nevezni a conn_path. Például:

conn_path .update_and_verify_fwon_usb_stop(handle) .map_err(|err| { println!("ERROR: Got unexpected result: {}", err); dispatcher::Error::CommandReturnedError })?;

Ez magában foglalja az alapokat. Ha megnézi a bázis tényleges forráskódját::verify_ro, ez egy bonyolultabb példa a start metódus hívás, figyelő, és a stop metódus hívás.

Command Help

Az alapértelmezett Súgó karakterláncok a parancsnév, a használati karakterlánc, a leírás karakterlánc, valamint a diszpécser API-n keresztül regisztrált opciók vagy zászlók használatával kerülnek kitöltésre.

Alternatív megoldásként a Súgó visszahívása beállítható a parancs regisztrálásakor az egyéni logika végrehajtásához, például egy bináris Súgó opció meghívásához. Például:

const EXECUTABLE: &str = "/usr/bin/vmc";pub fn register(dispatcher: &mut Dispatcher) { dispatcher.register_command( Command::new("vmc".to_string(), "".to_string(), "".to_string()) .set_command_callback(Some(execute_vmc)) .set_help_callback(vmc_help), );}fn vmc_help(_cmd: &Command, w: &mut dyn Write, _level: usize) { let mut sub = process::Command::new(EXECUTABLE) .arg("--help") .stdout(Stdio::piped()) .spawn() .unwrap(); if copy(&mut sub.stdout.take().unwrap(), w).is_err() { panic!(); } if sub.wait().is_err() { panic!(); }}

parancsok leértékelése

Ha egy crosh parancsot más felhasználói felülettel (például chrome:// page) szeretne helyettesíteni, és elegánsan le szeretné értékcsökkenteni a parancsot egy barátságos megjegyzés hátrahagyásával, ha az emberek megpróbálják használni, itt van az űrlap.

# Set the vars to pass the unittests ...USAGE_storage_status=''HELP_storage_status=''# ... then unset them to hide the command from "help" output.unset USAGE_storage_status HELP_storage_statuscmd_storage_status() ( # TODO: Delete this after the R## release branch. echo "Removed. See storage_info section in chrome://system")

győződjön meg róla, hogy hozzáadja a TODO megjegyzést, hogy az emberek a jövőben tudják, mikor rendben van a tisztítás.

tesztelés

iteratív fejlesztés

a./crosh futtatható az asztali rendszeren, hogy Minta héjat kapjon. Itt gyorsan tesztelheti az alapvető interakciókat (például az argumentum elemzését), vagy ellenőrizheti a Súgó kimenetét. Nem férhet hozzá a CrOS szolgáltatásokhoz, amelyekkel sok crosh parancs elvárja, hogy beszéljen (D-buszon keresztül), így ezek a parancsok meghiúsulnak.

Ha be szeretné tölteni a dev mode modulokat, használhatja a ./crosh --dev. Csak helyi modulokat tölt be (./dev.d/), így ha a modul máshol él, akkor ideiglenesen másolhatja itt.

hasonlóképpen, ha cserélhető eszközmodulokat szeretne betölteni, használhatja a ./crosh --removable.

Unittests

az egységtesztek futtatásához hívja a cargo test --workspace – t a crosh mappában, vagy futtassa a emege-${BOARD} crosh && FEATURES=test emerge-${BOARD}

./run_tests.shlegacy unittest runner alapvető stílus-és hangosság-ellenőrzéseket végez. Futtassa a shell kód bármilyen változásával szemben!

Future Work

bárki nyugodtan vegye fel ezeket az ötleteket, és próbálja meg végrehajtani őket:).

• mozgassa a helyén végrehajtott összes többi parancsot a debugd hívásokhoz, hogy azok D-buszon keresztül elvégezhetők legyenek.
• futtassa magát egy korlátozott homokozóban (névterek / seccomp / stb…). Miután az összes parancs IPC-n keresztül történik, nincs szükség Priv-k megtartására. Lehet, hogy ez függ dev mód, bár így nem törik shell.
• további örökölt shell parancsok áttelepítése Rustra. Ezt a parancs áttelepítésével egyidejűleg is meg lehet tenni a debugd-re.

Legacy Crosh Documentation

Crosh eredetileg shell nyelven íródott. Az írás idején sok parancs még mindig a héjban marad, és még át kell vinni a rozsda keresztbe. Ezt a dokumentációt itt tartjuk a parancsok karbantartásához.

Command API

minden parancshoz két változót és egy függvényt definiál. Nincs szükség az új parancsok regisztrálására bárhol, mivel a crosh megvizsgálja saját futásidejű környezetét, hogy felfedezze őket.

így regisztrálna egy új foo parancsot.

# A short description of arguments that this command accepts.USAGE_foo='<some args>'HELP_foo=' Extended description of this command.'# Not required, but lets crosh detect if the foo program is available in the# current system (e.g. the package is not installed on all devices). If it# isn't available, crosh will automatically display an error message and never# call cmd_foo.EXEC_foo='/full/path/to/program'cmd_foo() ( # Implementation for the foo command. # You should validate $# and "$@" and process them first. # For invalid args, call the help function with an error message # before returning non-zero. ...foo code goes here!...)

az új parancs felépítésével kapcsolatos további részletekért lásd az alábbi tervezési részt.

Command Help

Ha a crosh parancs egyszerűen egy külső programhoz szólít fel a feldolgozás elvégzéséhez, és ez a program már kínál használati adatokat, akkor valószínűleg nem akarja megismételni a dolgokat. Ezt a forgatókönyvet egy help_foo függvény meghatározásával kezelheti, amely a megfelelő hívást kezdeményezi.

# Set the help string so crosh can discover us automatically.HELP_foo=''cmd_foo() ( ...)help_foo() ( /some/command --help)

vegye figyelembe, hogy még mindig beállítottuk a HELP_foo. Erre azért van szükség, hogy a crosh automatikusan felfedezzen minket, és megjelenítsen minket a megfelelő felhasználói listákon (például a help_advanced parancs). Nem kell beállítanunk aUSAGE_foo értéket, mivel ahelp_foo függvény ezt teszi számunkra.

Bujkál Parancsok

Ha egy parancs még nem kész “főműsoridőben”, lehet, hogy a crosh a korai tesztelés, de nem jelenik meg a help kimenet, ahol a felhasználók könnyen megtalálni (persze, a kód az összes nyilvános, tehát bárki, aki olvassa a tényleges forrást lehet találni). Itt van, hogyan kell csinálni.

# Set the vars to pass the unittests ...USAGE_vmc=''HELP_vmc=''# ... then unset them to hide the command from "help" output.unset USAGE_vmc HELP_vmccmd_vmc() ( ...)