1 //! # Proxmox REST server
3 //! This module provides convenient building blocks to implement a
8 //! * highly threaded code, uses Rust async
9 //! * static API definitions using schemas
10 //! * restartable systemd daemons using `systemd_notify`
11 //! * support for long running worker tasks (threads or async tokio tasks)
12 //! * supports separate access and authentication log files
13 //! * extra control socket to trigger management operations
14 //! - logfile rotation
15 //! - worker task management
16 //! * generic interface to authenticate user
18 use std
::sync
::atomic
::{Ordering, AtomicBool}
;
19 use std
::future
::Future
;
22 use anyhow
::{bail, format_err, Error}
;
24 use hyper
::{Body, Response, Method}
;
25 use http
::request
::Parts
;
28 use proxmox
::tools
::fd
::Fd
;
29 use proxmox
::sys
::linux
::procfs
::PidStat
;
30 use proxmox
::api
::UserInformation
;
31 use proxmox
::tools
::fs
::CreateOptions
;
34 pub use compression
::*;
41 pub use environment
::*;
47 pub use command_socket
::*;
50 pub use file_logger
::{FileLogger, FileLogOptions}
;
53 pub use api_config
::ApiConfig
;
56 pub use rest
::RestServer
;
59 pub use worker_task
::*;
64 /// Authentication Error
70 impl From
<Error
> for AuthError
{
71 fn from(err
: Error
) -> Self {
72 AuthError
::Generic(err
)
76 /// User Authentication and index/root page generation methods
77 pub trait ServerAdapter
: Send
+ Sync
{
79 /// Returns the index/root page
82 rest_env
: RestEnvironment
,
84 ) -> Pin
<Box
<dyn Future
<Output
= Response
<Body
>> + Send
>>;
86 /// Extract user credentials from headers and check them.
88 /// If credenthials are valid, returns the username and a
89 /// [UserInformation] object to query additional user data.
92 headers
: &'a HeaderMap
,
94 ) -> Pin
<Box
<dyn Future
<Output
= Result
<(String
, Box
<dyn UserInformation
+ Sync
+ Send
>), AuthError
>> + Send
+ 'a
>>;
98 lazy_static
::lazy_static
!{
99 static ref PID
: i32 = unsafe { libc::getpid() }
;
100 static ref PSTART
: u64 = PidStat
::read_from_pid(Pid
::from_raw(*PID
)).unwrap().starttime
;
103 /// Retruns the current process ID (see [libc::getpid])
105 /// The value is cached at startup (so it is invalid after a fork)
106 pub(crate) fn pid() -> i32 {
110 /// Returns the starttime of the process (see [PidStat])
112 /// The value is cached at startup (so it is invalid after a fork)
113 pub(crate) fn pstart() -> u64 {
117 /// Helper to write the PID into a file
118 pub fn write_pid(pid_fn
: &str) -> Result
<(), Error
> {
119 let pid_str
= format
!("{}\n", *PID
);
120 proxmox
::tools
::fs
::replace_file(pid_fn
, pid_str
.as_bytes(), CreateOptions
::new())
123 /// Helper to read the PID from a file
124 pub fn read_pid(pid_fn
: &str) -> Result
<i32, Error
> {
125 let pid
= proxmox
::tools
::fs
::file_get_contents(pid_fn
)?
;
126 let pid
= std
::str::from_utf8(&pid
)?
.trim();
127 pid
.parse().map_err(|err
| format_err
!("could not parse pid - {}", err
))
130 /// Returns the control socket path for a specific process ID.
132 /// Note: The control socket always uses @/run/proxmox-backup/ as
133 /// prefix for historic reason. This does not matter because the
134 /// generated path is unique for each ``pid`` anyways.
135 pub fn ctrl_sock_from_pid(pid
: i32) -> String
{
136 // Note: The control socket always uses @/run/proxmox-backup/ as prefix
137 // for historc reason.
138 format
!("\0{}/control-{}.sock", "/run/proxmox-backup", pid
)
141 /// Returns the control socket path for this server.
142 pub fn our_ctrl_sock() -> String
{
143 ctrl_sock_from_pid(*PID
)
146 static SHUTDOWN_REQUESTED
: AtomicBool
= AtomicBool
::new(false);
148 /// Request a server shutdown (usually called from [catch_shutdown_signal])
149 pub fn request_shutdown() {
150 SHUTDOWN_REQUESTED
.store(true, Ordering
::SeqCst
);
151 crate::server_shutdown();
154 /// Returns true if there was a shutdown request.
156 pub fn shutdown_requested() -> bool
{
157 SHUTDOWN_REQUESTED
.load(Ordering
::SeqCst
)
160 /// Raise an error if there was a shutdown request.
161 pub fn fail_on_shutdown() -> Result
<(), Error
> {
162 if shutdown_requested() {
163 bail
!("Server shutdown requested - aborting task");
168 /// safe wrapper for `nix::sys::socket::socketpair` defaulting to `O_CLOEXEC` and guarding the file
170 pub fn socketpair() -> Result
<(Fd
, Fd
), Error
> {
171 use nix
::sys
::socket
;
172 let (pa
, pb
) = socket
::socketpair(
173 socket
::AddressFamily
::Unix
,
174 socket
::SockType
::Stream
,
176 socket
::SockFlag
::SOCK_CLOEXEC
,
182 /// Extract a specific cookie from cookie header.
183 /// We assume cookie_name is already url encoded.
184 pub fn extract_cookie(cookie
: &str, cookie_name
: &str) -> Option
<String
> {
185 for pair
in cookie
.split('
;'
) {
186 let (name
, value
) = match pair
.find('
='
) {
187 Some(i
) => (pair
[..i
].trim(), pair
[(i
+ 1)..].trim()),
188 None
=> return None
, // Cookie format error
191 if name
== cookie_name
{
192 use percent_encoding
::percent_decode
;
193 if let Ok(value
) = percent_decode(value
.as_bytes()).decode_utf8() {
194 return Some(value
.into());
196 return None
; // Cookie format error
204 /// normalize uri path
206 /// Do not allow ".", "..", or hidden files ".XXXX"
207 /// Also remove empty path components
208 pub fn normalize_uri_path(path
: &str) -> Result
<(String
, Vec
<&str>), Error
> {
209 let items
= path
.split('
/'
);
211 let mut path
= String
::new();
212 let mut components
= vec
![];
218 if name
.starts_with('
.'
) {
219 bail
!("Path contains illegal components.");
223 components
.push(name
);
226 Ok((path
, components
))