use argh::{FromArgValue, FromArgs};
use single_instance::SingleInstance;
use crate::{
dbg_backend::DebugBackend,
error::{Error, Result},
gdb::GdbClient,
kd::KdBackend,
memory_backend::MemoryBackend,
repl::start_repl,
script::ScriptInstallOptions,
};
mod backend;
mod bugchecks;
mod dbg_backend;
mod debugger;
mod diagnostics;
mod error;
mod expr;
mod gdb;
mod guest;
mod host;
mod kd;
mod memory;
mod memory_backend;
mod repl;
mod script;
mod symbols;
mod types;
mod ui;
mod unwind;
mod virsh;
#[derive(Clone, Copy, PartialEq, Eq)]
enum BackendKind {
Gdb,
Kd,
Memory,
}
impl FromArgValue for BackendKind {
fn from_arg_value(value: &str) -> std::result::Result<Self, String> {
match value {
"gdb" => Ok(BackendKind::Gdb),
"kd" => Ok(BackendKind::Kd),
"memory" => Ok(BackendKind::Memory),
other => Err(format!(
"unknown backend '{other}': expected 'kd', 'gdb', or 'memory'"
)),
}
}
}
#[derive(FromArgs)]
struct Args {
#[argh(switch, short = 'v', long = "version")]
version: bool,
#[argh(switch, long = "force-download-symbols")]
redownload_symbols: bool,
#[argh(switch, long = "gdbstub-instructions")]
gdbstub_instructions: bool,
#[argh(switch, long = "kd-instructions")]
kd_instructions: bool,
#[argh(option, short = 'b', long = "backend", default = "BackendKind::Kd")]
backend: BackendKind,
#[argh(option, long = "connect")]
connect: Option<String>,
#[argh(subcommand)]
command: Option<Command>,
}
#[derive(FromArgs)]
#[argh(subcommand)]
enum Command {
Scripts(ScriptsCommand),
Virsh(VirshCommand),
}
#[derive(FromArgs)]
#[argh(subcommand, name = "virsh")]
struct VirshCommand {}
#[derive(FromArgs)]
#[argh(subcommand, name = "scripts")]
struct ScriptsCommand {
#[argh(subcommand)]
command: ScriptsSubcommand,
}
#[derive(FromArgs)]
#[argh(subcommand)]
enum ScriptsSubcommand {
Install(ScriptsInstallCommand),
List(ScriptsListCommand),
}
#[derive(FromArgs)]
#[argh(subcommand, name = "install")]
struct ScriptsInstallCommand {
#[argh(positional)]
source: Option<String>,
#[argh(switch, long = "force")]
force: bool,
#[argh(switch, long = "yes", short = 'y')]
yes: bool,
}
#[derive(FromArgs)]
#[argh(subcommand, name = "list")]
struct ScriptsListCommand {}
#[cfg(not(target_os = "linux"))]
compile_error!("This application only runs on Linux hosts.");
static GDBSTUB_INSTRUCTIONS: &str = "The gdb backend talks to QEMU's gdbstub instead of Windows KD.
It does not require Windows debug mode, but it loses Windows-native
KD behavior such as bugcheck debug text and KD reboot signalling.
To enable it, pass the following arguments to QEMU:
-s -S
Then run ntoseye with:
ntoseye --backend gdb
If you are running QEMU via commandline, simply append the arguments
to your existing command.
If you are running QEMU via virt-manager, you must edit the libvirt
XML file, which can be done through their GUI. Once there, add:
<domain xmlns:qemu=\"http://libvirt.org/schemas/domain/qemu/1.0\" type=\"kvm\">
...
<qemu:commandline>
<qemu:arg value=\"-s\"/>
<qemu:arg value=\"-S\"/>
</qemu:commandline>
</domain>";
static KD_INSTRUCTIONS: &str = "The KD backend is ntoseye's default backend.
It speaks the same wire protocol WinDbg uses, over a serial pipe
between QEMU and ntoseye. It requires Windows to be booted in debug
mode (which removes the 'stealth' property of the gdb backend:
anti-debug code, PatchGuard, and even some Windows behaviors change
when /debug is on).
GUEST: enable kernel debugging over a serial port (run as
Administrator, then reboot):
bcdedit /debug on
bcdedit /dbgsettings serial debugport:1 baudrate:115200
If your hypervisor wires the KD serial as COM2 (see the libvirt
note below), use 'debugport:2' instead.
QEMU (commandline): route COM1 to a host-side Unix socket. The
path here matches ntoseye's default; adjust both sides if you pick
a different one:
-chardev socket,id=kd,path=/tmp/ntoseye-kd.sock,server=on,wait=off -serial chardev:kd
QEMU via virt-manager / libvirt: virt-manager auto-adds a <serial>
console device on every VM, and it claims COM1. Either replace or
remove that device so the KD chardev becomes COM1 (recommended), or
leave it in place and the KD chardev will be COM2 (use 'debugport:2'
in bcdedit instead of 'debugport:1').
OPTION A (recommended): replace the auto-added <serial> with one
that points at our Unix socket. KD is COM1, 'debugport:1' is correct.
<serial type=\"unix\">
<source mode=\"bind\" path=\"/tmp/ntoseye-kd.sock\"/>
<target type=\"isa-serial\" port=\"0\"/>
</serial>
OPTION B: leave the auto-added serial alone and append the KD
chardev via qemu:commandline. KD ends up as COM2, so use
'debugport:2' in bcdedit.
<domain xmlns:qemu=\"http://libvirt.org/schemas/domain/qemu/1.0\" type=\"kvm\">
...
<qemu:commandline>
<qemu:arg value=\"-chardev\"/>
<qemu:arg value=\"socket,id=kd,path=/tmp/ntoseye-kd.sock,server=on,wait=off\"/>
<qemu:arg value=\"-serial\"/>
<qemu:arg value=\"chardev:kd\"/>
</qemu:commandline>
</domain>
Once the guest is booting (or already booted and waiting for the
debugger), run:
ntoseye --connect /tmp/ntoseye-kd.sock
ntoseye waits 8 seconds for the initial KD handshake by default.
For unusually slow guests, override it with:
NTOSEYE_KD_TIMEOUT=20 ntoseye";
fn main() {
if let Err(e) = run() {
diagnostics::print_error(e);
std::process::exit(1);
}
}
fn run() -> Result<()> {
let args: Args = argh::from_env();
if args.version {
println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
return Ok(());
}
if args.gdbstub_instructions {
println!("{}", GDBSTUB_INSTRUCTIONS);
return Ok(());
}
if args.kd_instructions {
println!("{}", KD_INSTRUCTIONS);
return Ok(());
}
if let Some(command) = args.command {
return match command {
Command::Virsh(_) => virsh::run_interactive(),
Command::Scripts(scripts) => match scripts.command {
ScriptsSubcommand::Install(install) => {
script::install_scripts(ScriptInstallOptions {
source: install.source,
force: install.force,
yes: install.yes,
})
}
ScriptsSubcommand::List(_) => script::list_scripts(),
},
};
}
let instance = SingleInstance::new("ntoseye").map_err(|err| {
Error::DebugInfo(format!("failed to create single-instance guard: {err:?}"))
})?;
if !instance.is_single() {
return Err(Error::AlreadyRunning);
}
symbols::FORCE_DOWNLOADS
.set(args.redownload_symbols)
.map_err(|_| {
Error::DebugInfo("symbol download flag was initialized before startup".into())
})?;
let mut debugger = debugger::DebuggerContext::new()?;
let mut backend: Box<dyn DebugBackend> = match args.backend {
BackendKind::Gdb => {
let addr = args.connect.as_deref().unwrap_or("127.0.0.1:1234");
Box::new(GdbClient::connect(addr)?)
}
BackendKind::Kd => {
let path = args.connect.as_deref().unwrap_or("/tmp/ntoseye-kd.sock");
Box::new(KdBackend::connect(path)?)
}
BackendKind::Memory => {
if args.connect.is_some() {
return Err(Error::DebugInfo(
"memory backend does not use --connect".to_string(),
));
}
Box::new(MemoryBackend::new())
}
};
start_repl(&mut debugger, backend.as_mut())
}