From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id AE27F1FF14F for ; Wed, 17 Jun 2026 18:48:33 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 40CC12FCE; Wed, 17 Jun 2026 18:48:29 +0200 (CEST) From: Hannes Laimer To: pve-devel@lists.proxmox.com Subject: [PATCH pve-manager 2/2] pvesh: add 'record' subcommand to trace user's API requests Date: Wed, 17 Jun 2026 18:47:49 +0200 Message-ID: <20260617164749.574759-3-h.laimer@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260617164749.574759-1-h.laimer@proxmox.com> References: <20260617164749.574759-1-h.laimer@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1781714815133 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.086 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [pveproxy.pm,pvesh.pm] Message-ID-Hash: QN46AER6POW3IXRQAG2HNHDNRPA6DHB7 X-Message-ID-Hash: QN46AER6POW3IXRQAG2HNHDNRPA6DHB7 X-MailFrom: h.laimer@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Given a user, `pvesh record ` records the api requests made by that user and translates them into their corresponding `pvesh` command. By default only writes (POST/PUT/DELETE) are recorded, with '--all' also reads (GET). Requests are recorded and printed as long as the command runs. Makes it easy to repeat things done through the webUI via a script, for example. Can only be run as root, like the rest of pvesh. Signed-off-by: Hannes Laimer --- PVE/CLI/pvesh.pm | 140 ++++++++++++++++++++++++++++++++++++++++ PVE/Service/pveproxy.pm | 1 + 2 files changed, 141 insertions(+) diff --git a/PVE/CLI/pvesh.pm b/PVE/CLI/pvesh.pm index acd9a605..fa01b01c 100755 --- a/PVE/CLI/pvesh.pm +++ b/PVE/CLI/pvesh.pm @@ -12,6 +12,7 @@ use PVE::RPCEnvironment; use PVE::RESTHandler; use PVE::CLIFormatter; use PVE::CLIHandler; +use PVE::APIServer::RequestRecorder; use PVE::API2Tools; use PVE::API2; use JSON; @@ -82,6 +83,37 @@ my $method_map = { delete => 'DELETE', }; +# reverse of $method_map: HTTP method -> pvesh command +my $command_map = { reverse %$method_map }; + +# turn a recorded request event into the equivalent, ready-to-run 'pvesh' command +my $event_to_pvesh = sub { + my ($event) = @_; + + my $method = $event->{method} // return undef; + my $cmd = $command_map->{$method} // return undef; + my $path = $event->{path} // return undef; + + my $args = ['pvesh', $cmd, $path]; + + my $params = $event->{params}; + if (ref($params) eq 'HASH') { + foreach my $key (sort keys %$params) { + my $val = $params->{$key}; + if (ref($val) eq 'ARRAY') { + push @$args, "--$key", $_ for @$val; + } elsif (ref($val)) { + # nested structure from a JSON request body - keep it as JSON + push @$args, "--$key", encode_json($val); + } else { + push @$args, "--$key", $val; + } + } + } + + return String::ShellQuote::shell_quote(@$args); +}; + sub check_proxyto { my ($info, $uri_param, $params) = @_; @@ -604,6 +636,113 @@ __PACKAGE__->register_method({ }, }); +__PACKAGE__->register_method({ + name => 'record', + path => 'record', + method => 'GET', + description => "Watch the API requests a user makes (for example via the web UI) and " + . "print them as the equivalent 'pvesh' commands. Stop with CTRL+C.", + protected => 1, + parameters => { + additionalProperties => 0, + properties => { + user => get_standard_option( + 'userid', + { + description => "Only record requests made by this user " + . "(also matches the user's API tokens).", + }, + ), + all => { + description => "Also record read-only (GET) requests. By default only " + . "writing requests (POST/PUT/DELETE) are recorded.", + type => 'boolean', + optional => 1, + default => 0, + }, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + die "only root can record API requests\n" if $> != 0; + + my $user = $param->{user}; + my $filter = { userid => $user, all => $param->{all} ? 1 : 0 }; + + my $id = PVE::APIServer::RequestRecorder::start_recording($filter); + + my $cleaned = 0; + my $cleanup = sub { + return if $cleaned; + $cleaned = 1; + PVE::APIServer::RequestRecorder::stop_recording($id); + }; + + local $SIG{INT} = local $SIG{TERM} = sub { + $cleanup->(); + print STDERR "\nrecording stopped\n"; + exit(0); + }; + + local $| = 1; # show recorded commands as they come in + + my $events_path = PVE::APIServer::RequestRecorder::events_path($id); + + eval { + my $fh; + my $pos = 0; + my $buf = ''; + my $ino = 0; + + while (1) { + # (re)open the spool if it appeared, got rotated to a new inode, + # or was truncated/recreated underneath us + if (my @st = stat($events_path)) { + if (!$fh || $st[1] != $ino || $st[7] < $pos) { + open($fh, '<', $events_path) + or die "unable to open event spool '$events_path' - $!\n"; + $ino = $st[1]; + $pos = 0; + $buf = ''; + } + } + + if ($fh) { + seek($fh, $pos, 0); # also clears EOF so we pick up appended data + my $chunk = do { local $/ = undef; <$fh> }; + if (defined($chunk) && length($chunk)) { + $pos += length($chunk); + $buf .= $chunk; + while ($buf =~ s/^([^\n]*)\n//) { + my $line = $1; + next if $line eq ''; + my $event = eval { decode_json($line) }; + if (!$event) { + next; + } + my $cmd = $event_to_pvesh->($event); + if (!defined($cmd)) { + next; + } + print "$cmd\n"; + } + } + } + + select(undef, undef, undef, 0.2); + } + }; + my $err = $@; + + $cleanup->(); + die $err if $err; + + return undef; + }, +}); + our $cmddef = { usage => [__PACKAGE__, 'usage', ['api_path']], get => [__PACKAGE__, 'get', ['api_path']], @@ -611,6 +750,7 @@ our $cmddef = { set => [__PACKAGE__, 'set', ['api_path']], create => [__PACKAGE__, 'create', ['api_path']], delete => [__PACKAGE__, 'delete', ['api_path']], + record => [__PACKAGE__, 'record', ['user']], }; 1; diff --git a/PVE/Service/pveproxy.pm b/PVE/Service/pveproxy.pm index c6011a00..1dc6fa0f 100755 --- a/PVE/Service/pveproxy.pm +++ b/PVE/Service/pveproxy.pm @@ -106,6 +106,7 @@ sub init { debug => $self->{debug}, trusted_env => 0, # not trusted, anyone can connect logfile => '/var/log/pveproxy/access.log', + request_recording => 1, # enable 'pvesh record' (front-end sees full request bodies) allow_from => $proxyconf->{ALLOW_FROM}, deny_from => $proxyconf->{DENY_FROM}, policy => $proxyconf->{POLICY}, -- 2.47.3