이것은 crosh,Chromium OS shell 의 홈페이지/설명서입니다. 지금 CrOS 장치에 있다면 Ctrl+Alt+T 를 쳐서 crosh 를 시작할 수 있어야합니다.CrOS 에 있지 않으면 유용한 것을하지 않을 가능성이 큽니다.:).

실행help에 대한 정보를 얻을 수 있는 명령하고 더 많은 것을 발견.

탭 완성을 사용하여 기존 명령을 빠르게 찾을 수도 있습니다.

그것은 모험이다!

Chromium OS 개발자를위한

이 섹션은 특히 crosh 를 수정/확장해야하는 경우 Chromium OS 에서 해킹하는 사람들을위한 것입니다.

보안 경고

전체 보안 검토없이 새 모듈을 설치하지 마십시오. Crosh 가로드하는 안전하지 않은 코드는 검증 된 모드의 사람들이 직접 사용할 수 있습니다. 즉,임의의 코드를 실행하고 사용자의 상태를 엉망으로 만드는 쉬운 공격 벡터입니다. 우리는 Cro 의 보안을 훼손하고 싶지 않습니다!

리뷰어를 찾고 있다면 살펴보십시오./소유자 파일.

파일이 사는 곳

Crosh 가 쉘에서 Rust 로 마이그레이션되고 있습니다. Crosh 실행되기 시작하면서 src/main.rs 하지만 대부분의 명령을 구현했으로 자신의 서브모듈 중 하나의 높은 수준의 모듈(예를 들어basedev).

maincrosh스크립트를 포함 기존 구현의 핵심 crosh 로직하는 동안 다른 유산 함수 라이브에서 모듈의 디렉토리입니다. Crosh 의 레거시 버전은 장치에crosh.sh로 설치됩니다.

원 Repos

모듈은 특정을 보거나 심하게 특정 패키지는,일반적으로 라이브로 널 그리고/또는 패키지입니다. 모든 CrOS 장치에서 항상 사용할 수있는 함수의 경우 해당 코드는이 repo 에 보관해야합니다.

잘 모르는 경우에는,요청에 [email protected].

추가하는 새로운 명령

먼저 결정의 구현 전략을 새로운 명령을 사용하는 것입니다. 전략을 선택할 때 어떤 권한과 권한이 필요한지 알면 도움이됩니다. 전략을 염두에두고 아래의 다양한 예제를 확인하십시오.

명령이자

crosh 쉘을 실행과 같은 환경에서는 브라우저(동일한 사용자/그룹,같은 리눅스는 네임스페이스,등등…). 따라서 crosh 에서 실행되는 도구 또는 획득하려는 정보는chronos사용자가 액세스 할 수 있어야합니다.

그러나 crosh 가 실제로 도구를 직접 실행하기를 거의 원하지 않습니다. 대신 debugd 데몬에 D-Bus 콜백을 추가하고 모든 요청을 보내야합니다. Debugd 에서 액세스를 더 잘 제어하고 도구를 잠글 수 있습니다. 그런 다음 crosh 에 존재하는 유일한 논리는 D-Bus IPC 호출이며 해당 프로그램의 출력을 표시합니다. Debugd 에 대한 논의는 여기에서 범위를 벗어나므로 대신 debugd 디렉토리를 확인하십시오.

예

예를 구현:

• D-Bus 방법 래퍼(debugd):기::verify_ro
  이 때 a D-Bus API 는 이미 계획하거나 crosh 이 부족하는 데 필요한 권한이나 기능입니다.
• 외부 바이너리 wrapper:기::ccd_pass
  이 때 이미 있는 명령행 도구를 구현하는 명령을 작동하는 실행할 경우로 크로노스와의 기능을 crosh.
• Rust 로 작성된 명령:base::arc
  이것은 추가 기능이 필요하지 않고 별도의 명령 줄 도구를 갖는 것이 정당화되지 않은 경우에 가장 적합합니다.

새 명령을 작성하기위한 샘플 워크 플로가 아래에 포함되어 있습니다.

모듈 설정

속할 명령에 적합한 모듈을 선택합니다. 드 모드 명령이 될 것입니다devbasebase를 모듈로 사용하지만 다른 경우에도 동일한 단계가 계속 적용되어야합니다.

그런 다음 명령 이름을 선택하고 해당 이름으로 하위 모듈을 만든 다음 상위 모듈에 등록하십시오. 이 예제 명령입니다verify_rosrc/base/verify_ro.rssrc/base/mod.rs

첫째,서브모듈 가져와야 하:

mod verify_ro;

두 번째 기록 기능(를 만들어 아래)할 필요가에 의해 호출 등록 함수에서 부모 모듈src/base/mod.rs:

pub fn register(dispatcher: &mut Dispatcher) { ... verify_ro::register(dispatcher); ...}

지금src/base/verify_ro.rs소스 파일 준비가 작성해야합니다. 이 최소한의 소스 파일이 있는지 확인합 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!();}

명령을 구현

이것은 가정의 위한 지침은 이미 완료합니다.

이후 권한 있는 작업 실행할 수 없습으로 Crosh(하지만 구현해야에서 debugd 또는 어디든지 다른 사람),예 아래에 초점을 맞추고 D-Bus 에서 특정하고 있는 것으로 간주하는 기존 D-Bus 는 방법을 요구에서 호출되는 새로운 Crosh 명령입니다.

주는 debugd 의 D-Bus 인터페이스는 이미 녹 바인딩을 통해 생성 개발-녹/system_api,그래서 바인딩 및 D-버스 연결을 가져올 수 있다:

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

탐색하려면 소스 코드의 생성되는 바인딩을 실행한 후 build_packages 살펴보고,다음과 같은 경로:

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

내 명령을 구현 D-버스 연결을 초기화해야 합니다. 이 예에서는 차단 연결이 사용됩니다.

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

버스 연결을 사용하여 다음을 수행할 수 있습니다 얻을 인터페이스를 원하는 서비스는 debugd 이 경우는 다음과 같습니다.

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

의 나머지 부분은 메소드 호출이 사용하는 사실을 가져온 특성system_api::client::OrgChromiumDebugdconn_path그는 멤버 함수의 지도하 D-Bus 방법이라고 할 수 있습에서conn_path. 예:

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

이것은 기본 사항을 다룹니다. 베이스에 대한 실제 소스 코드를 보면::verify_ro 는 시작 메소드 호출,감시자 및 중지 메소드 호출과 함께보다 복잡한 예제를 제공합니다.

명령에 도움

기본 도움이 문자열을 채워지 명령을 사용하여 이름,사용자 문자열 설명 문자열이며,어떤 옵션이나 플래그 등록을 통해 디스패처 API 를 사용합니다.

또는 도움말 콜백을 설정할 수 있습을 등록할 때 명령을 수행하는 사용자 정의 논리아를 호출하는 데 도움이션 옵션의 바이너리입니다. 예를 들어:

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!(); }}

비하하는 명령

경우를 대체하려고 crosh 명령으로 몇 가지 다른 UI(같은 chrome://페이지),그리고 당신이 원하면 더 이상 사용하지 않는 것 명령이 정상적으로 떠나는 뒤에 친절한 주면 사람들은 그것을 사용하려고,여기는 형태입니다.나중에 정리해도 괜찮을 때 사람들이 알 수 있도록 할일 주석을 추가해야합니다.

테스트

반복 개발

데스크톱 시스템에서./crosh를 실행하여 샘플 쉘을 얻을 수 있습니다. 여기에서 기본 상호 작용(예:인수 구문 분석)을 빠르게 테스트하거나 도움말 출력을 확인할 수 있습니다. 많은 crosh 명령이(D-버스를 통해)이야기 할 것으로 예상되는 CrOS 서비스에 액세스 할 수 없으므로 해당 명령이 실패합니다.

dev 모드 모듈을로드하려는 경우./crosh --dev./dev.d/),그래서 만약 당신의 모듈을 생활,다른 곳에서 당신이 그것을 복사 할 수 있다.

마찬가지로 이동식 장치 모듈을로드하려는 경우./crosh --removable를 사용할 수 있습니다.

Unittests

단위 테스트를 실행합 하거나 전화cargo test --workspace에 crosh 폴더 또는 실행하는emege-${BOARD} crosh && FEATURES=test emerge-${BOARD}

./run_tests.sh레거시 unittest 에 대한 여러 주자는 수행의 무리는 기본적인 스타일과 건전성을 확인합니다. 쉘 코드에 대한 변경 사항에 대해 실행하십시오!

미래의 작업

누구나 이러한 아이디어를 집어 들고 구현하려고 노력해야합니다:).

• 장소에 구현 된 나머지 명령을 d-버스를 통해 수행 할 수 있도록 debugd 호출로 이동하십시오.
• 제한된 샌드 박스(네임 스페이스/seccomp/등)에서 crosh 자체를 실행합니다…). 모든 명령이 IPC 를 통해 수행되면 priv 를 유지할 필요가 없습니다. 그러나 dev 모드에 의존하게 만들 수 있으므로shell를 중단하지 않습니다.
• 추가 레거시 쉘 명령을 Rust 로 마이그레이션합니다. 이 작업은 명령을 debugd 로 마이그레이션하는 것과 동시에 수행할 수도 있습니다.

레거시 Crosh 문서

Crosh 는 원래 쉘로 작성되었습니다. 명령의 많은 글을 쓰는 시점에서 여전히 쉘에 남아 아직 녹 crosh 에 이상 이식 할 수있다. 이 설명서는 이러한 명령의 유지 관리를 위해 여기에 보관됩니다.

명령 API

모든 명령에 대해 두 개의 변수와 하나의 함수를 정의합니다. Crosh 가이를 발견하기 위해 자체 런타임 환경을 검사 할 것이므로 어디서나 새 명령을 등록 할 필요가 없습니다.

다음은 새foo명령을 등록하는 방법입니다.

# 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!...)

볼 디자인 섹션에 대한 자세한 내용은 아래를 무엇을 어떻게 구조화하는 새로운 명령입니다.

명령에 도움

경우 crosh 단순히 명령을 호출을 외부 프로그램을 처리하는 프로그램으로 제공하는 사용량 세부 정보,당신은 아마이 있고 싶지 않을 중복한 것들입니다. 각 호출을 만드는help_foo함수를 정의하여이 시나리오를 처리 할 수 있습니다.

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

아직HELP_foo를 설정했음을 유의하십시오. 이것은 crosh 가 자동으로 우리를 발견하고 관련 사용자 직면 목록(help_advancedUSAGE_foohelp_foo함수는 않습니다.

숨어있는 명령

경우는 명령은 아직 준비를 위해”시간”,당신은 그것을 가지고 할 수 있습에서 crosh 위해 초기 테스트,하지만 그것에는help출력 사용자가 쉽게 발견 할 수 있습니다 그것은(물론,코드가 모든 공용,그래서 누구나 읽고 실제 소스를 찾을 수 있습니다). 여기 당신이 그것을하는 방법입니다.나는 이것을 할 수 없다.