qm.conf

package: pve-qemu-server

title: qm.conf(5)

text:
# qm.conf(5)

## NAME
qm.conf - Proxmox VE Virtual Machine Configuration

## SYNOPSIS
/etc/pve/qemu-server/<VMID>.conf

## DESCRIPTION
The /etc/pve/qemu-server/<VMID>.conf files stores VM configuration, where "VMID" is the numeric ID of the given VM.

Note IDs < 100 are reserved for internal purposes.

## FILE FORMAT
The file uses a simple colon separated key/value format. Each line has the following format:

```
OPTION: value
```

Blank lines in the file are ignored, and lines starting with a # character are treated as comments and are also ignored.

One can use the qm command to generate and modify those files.

## OPTIONS
acpi: <boolean> (default = 1)

Enable/disable ACPI.

affinity: <string>

List of host cores used to execute guest processes, for example: 0,5,8-11

agent: [enabled=]<1|0> [,freeze-fs=<1|0>] [,fstrim_cloned_disks=<1|0>] [,type=<virtio|isa>]

Enable/disable communication with the QEMU Guest Agent and its properties. enabled=<boolean> (default = 0)

Enable/disable communication with a QEMU Guest Agent (QGA) running in the VM.

freeze-fs=<boolean> (default = 1)

Whether to issue the guest-fsfreeze-freeze and guest-fsfreeze-thaw QEMU guest agent commands. Backups in snapshot mode, clones, snapshots without RAM, importing disks from a running guest, and replications normally issue a guest-fsfreeze-freeze and a respective thaw command when the QEMU Guest agent option is enabled in the guest’s configuration and the agent is running inside of the guest. The deprecated freeze-fs-on-backup setting is treated as an alias for this setting.

fstrim_cloned_disks=<boolean> (default = 0)

Run fstrim after moving a disk or migrating the VM.

type=<isa | virtio> (default = virtio)

Select the agent type

allow-ksm: <boolean> (default = 1)

Allow memory pages of this guest to be merged via KSM (Kernel Samepage Merging).

amd-sev: [type=]<sev-type> [,allow-smt=<1|0>] [,kernel-hashes=<1|0>] [,no-debug=<1|0>] [,no-key-sharing=<1|0>]

Secure Encrypted Virtualization (SEV) features by AMD CPUs allow-smt=<boolean> (default = 1)

Sets policy bit to allow Simultaneous Multi Threading (SMT) (Ignored unless for SEV-SNP)

kernel-hashes=<boolean> (default = 0)

Add kernel hashes to guest firmware for measured linux kernel launch

no-debug=<boolean> (default = 0)

Sets policy bit to disallow debugging of guest

no-key-sharing=<boolean> (default = 0)

Sets policy bit to disallow key sharing with other guests (Ignored for SEV-SNP)

type=<sev-type>

Enable standard SEV with type=std or enable experimental SEV-ES with the es option or enable experimental SEV-SNP with the snp option.

arch: <aarch64 | x86_64>

Virtual processor architecture. Defaults to the host architecture.

args: <string>

Arbitrary arguments passed to kvm, for example: args: -no-reboot -smbios type=0,vendor=FOO

Note

this option is for experts only.

audio0: device=<ich9-intel-hda|intel-hda|AC97> [,driver=<spice|none>]

Configure a audio device, useful in combination with QXL/Spice. device=<AC97 | ich9-intel-hda | intel-hda>

Configure an audio device.

driver=<none | spice> (default = spice)

Driver backend for the audio device.

autostart: <boolean> (default = 0)

Automatic restart after crash (currently ignored).

balloon: <integer> (0 - N)

Amount of target RAM for the VM in MiB. The balloon driver is enabled by default, unless it is explicitly disabled by setting the value to zero.

bios: <ovmf | seabios> (default = seabios)

Select BIOS implementation.

boot: [[legacy=]<[acdn]{1,4}>] [,order=<device[;device...]>]

Specify guest boot order. Use the order= sub-property as usage with no key or legacy= is deprecated. legacy=<[acdn]{1,4}> (default = cdn)

Boot on floppy (a), hard disk (c), CD-ROM (d), or network (n). Deprecated, use order= instead.

order=<device[;device...]>

The guest will attempt to boot from devices in the order they appear here. Disks, optical drives and passed-through storage USB devices will be directly booted from, NICs will load PXE, and PCIe devices will either behave like disks (e.g. NVMe) or load an option ROM (e.g. RAID controller, hardware NIC).

Note that only devices in this list will be marked as bootable and thus loaded by the guest firmware (BIOS/UEFI). If you require multiple disks for booting (e.g. software-raid), you need to specify all of them here.

Overrides the deprecated legacy=[acdn]* value when given.

bootdisk: (ide|sata|scsi|virtio)\d+

Enable booting from specified disk. Deprecated: Use boot: order=foo;bar instead.

cdrom: <volume>

This is an alias for option -scsi7

cicustom: [meta=<volume>] [,network=<volume>] [,user=<volume>] [,vendor=<volume>]

cloud-init: Specify custom files to replace the automatically generated ones at start. meta=<volume>

Specify a custom file containing all meta data passed to the VM via cloud-init. This is provider specific meaning configdrive2 and nocloud differ.

network=<volume>

To pass a custom file containing all network data to the VM via cloud-init.

user=<volume>

To pass a custom file containing all user data to the VM via cloud-init.

vendor=<volume>

To pass a custom file containing all vendor data to the VM via cloud-init.

cipassword: <string>

cloud-init: Password to assign the user. Using this is generally not recommended. Use ssh keys instead. Also note that older cloud-init versions do not support hashed passwords.

citype: <configdrive2 | nocloud | opennebula>

Specifies the cloud-init configuration format. The default depends on the configured operating system type (ostype. We use the nocloud format for Linux, and configdrive2 for windows.

ciupgrade: <boolean> (default = 1)

cloud-init: do an automatic package upgrade after the first boot.

ciuser: <string>

cloud-init: User name to change ssh keys and password for instead of the image’s configured default user.

cores: <integer> (1 - N) (default = 1)

The number of cores per socket.

cpu: [[cputype=]<string>] [,flags=<+FLAG[;-FLAG...]>] [,guest-phys-bits=<integer>] [,hidden=<1|0>] [,hv-vendor-id=<vendor-id>] [,level=<integer>] [,phys-bits=<8-64|host>] [,reported-model=<enum>]

Emulated CPU type. cputype=<string> (default = kvm64)

Emulated CPU type. Can be default or custom name (custom model names must be prefixed with custom-).

flags=<+FLAG[;-FLAG...]>

List of additional CPU flags separated by ;. Use +FLAG to enable, -FLAG to disable a flag. There is a special nested-virt shorthand which controls nested virtualization for the current CPU (svm for AMD and vmx for Intel). Custom CPU models can specify any flag supported by QEMU/KVM, VM-specific flags must be from the following set for security reasons: aes, amd-no-ssb, amd-ssbd, hv-evmcs, hv-tlbflush, ibpb, md-clear, nested-virt, pcid, pdpe1gb, spec-ctrl, ssbd, virt-ssbd

guest-phys-bits=<integer> (32 - 64)

Number of physical address bits available to the guest.

hidden=<boolean> (default = 0)

Do not identify as a KVM virtual machine. Only affects vCPUs with x86-64 architecture.

hv-vendor-id=<vendor-id>

The Hyper-V vendor ID. Some drivers or programs inside Windows guests need a specific ID.

level=<integer> (0 - 4294967295)

Maximum input value for the basic CPUID leaves the guest can query - that is the vendor (leaf 0), family/model/stepping and feature bits (leaf 1), cache and topology info (leaves 4 and B), and so on. Higher-numbered leaves are hidden. Setting 30 is a common workaround for Hyper-V boot failures on Windows guests running on recent Intel hosts. Only applies when the vCPU architecture is x86_64.

phys-bits=<8-64|host>

The physical memory address bits that are reported to the guest OS. Should be smaller or equal to the host’s. Set to host to use value from host CPU, but note that doing so will break live migration to CPUs with other values.

reported-model=<486 | Broadwell | Broadwell-IBRS | Broadwell-noTSX | Broadwell-noTSX-IBRS | Cascadelake-Server | Cascadelake-Server-noTSX | Cascadelake-Server-v2 | Cascadelake-Server-v4 | Cascadelake-Server-v5 | ClearwaterForest | Conroe | Cooperlake | Cooperlake-v2 | EPYC | EPYC-Genoa | EPYC-Genoa-v2 | EPYC-IBPB | EPYC-Milan | EPYC-Milan-v2 | EPYC-Milan-v3 | EPYC-Rome | EPYC-Rome-v2 | EPYC-Rome-v3 | EPYC-Rome-v4 | EPYC-Rome-v5 | EPYC-Turin | EPYC-v3 | EPYC-v4 | EPYC-v5 | GraniteRapids | GraniteRapids-v2 | GraniteRapids-v3 | Haswell | Haswell-IBRS | Haswell-noTSX | Haswell-noTSX-IBRS | Icelake-Client | Icelake-Client-noTSX | Icelake-Server | Icelake-Server-noTSX | Icelake-Server-v3 | Icelake-Server-v4 | Icelake-Server-v5 | Icelake-Server-v6 | Icelake-Server-v7 | IvyBridge | IvyBridge-IBRS | KnightsMill | Nehalem | Nehalem-IBRS | Opteron_G1 | Opteron_G2 | Opteron_G3 | Opteron_G4 | Opteron_G5 | Penryn | SandyBridge | SandyBridge-IBRS | SapphireRapids | SapphireRapids-v2 | SapphireRapids-v3 | SapphireRapids-v4 | SierraForest | SierraForest-v2 | SierraForest-v3 | Skylake-Client | Skylake-Client-IBRS | Skylake-Client-noTSX-IBRS | Skylake-Client-v4 | Skylake-Server | Skylake-Server-IBRS | Skylake-Server-noTSX-IBRS | Skylake-Server-v4 | Skylake-Server-v5 | Westmere | Westmere-IBRS | a64fx | athlon | core2duo | coreduo | cortex-a35 | cortex-a53 | cortex-a55 | cortex-a57 | cortex-a710 | cortex-a72 | cortex-a76 | host | kvm32 | kvm64 | max | neoverse-n1 | neoverse-n2 | neoverse-v1 | pentium | pentium2 | pentium3 | phenom | qemu32 | qemu64> (default = kvm64)

CPU model and vendor to report to the guest. Must be a QEMU/KVM supported model. Only valid for custom CPU model definitions, default models will always report themselves to the guest OS.

cpulimit: <number> (0 - 128) (default = 0)

Limit of CPU usage.

Note

If the computer has 2 CPUs, it has total of 2 CPU time. Value 0 indicates no CPU limit.

cpuunits: <integer> (1 - 262144) (default = cgroup v1: 1024, cgroup v2: 100)

CPU weight for a VM. Argument is used in the kernel fair scheduler. The larger the number is, the more CPU time this VM gets. Number is relative to weights of all the other running VMs.

description: <string>

Description for the VM. Shown in the web-interface VM’s summary. This is saved as comment inside the configuration file.

efidisk0: [file=]<volume> [,efitype=<2m|4m>] [,format=<enum>] [,ms-cert=<enum>] [,pre-enrolled-keys=<1|0>] [,size=<DiskSize>]

Configure a disk for storing EFI vars. efitype=<2m | 4m> (default = 2m)

Size and type of the OVMF EFI vars. 4m is newer and recommended, and required for Secure Boot. For backwards compatibility, 2m is used if not otherwise specified. Ignored for VMs with arch=aarch64 (ARM).

file=<volume>

The drive’s backing volume.

format=<cloop | qcow | qcow2 | qed | raw | vmdk>

The drive’s backing file’s data format.

ms-cert=<2011 | 2023 | 2023k | 2023w> (default = 2011)

Informational marker indicating the version of the latest Microsoft UEFI certificates that have been enrolled by Proxmox VE. The value 2023k means that the Microsoft UEFI CA 2023, the Windows UEFI CA 2023 and the Microsoft Corporation KEK 2K CA 2023 certificates are included. The values 2023 and 2023w are deprecated and for compatibility only.

pre-enrolled-keys=<boolean> (default = 0)

Use am EFI vars template with distribution-specific and Microsoft Standard keys enrolled, if used with efitype=4m. Note that this will enable Secure Boot by default, though it can still be turned off from within the VM.

size=<DiskSize>

Disk size. This is purely informational and has no effect.

freeze: <boolean>

Freeze CPU at startup (use c monitor command to start execution).

hookscript: <string>

Script that will be executed during various steps in the vms lifetime.

hostpci[n]: [[host=]<HOSTPCIID[;HOSTPCIID2...]>] [,device-id=<hex id>] [,driver=<vfio|keep>] [,legacy-igd=<1|0>] [,mapping=<mapping-id>] [,mdev=<string>] [,pcie=<1|0>] [,rombar=<1|0>] [,romfile=<string>] [,sub-device-id=<hex id>] [,sub-vendor-id=<hex id>] [,vendor-id=<hex id>] [,x-vga=<1|0>]

Map host PCI devices into guest.

Note

This option allows direct access to host hardware. So it is no longer possible to migrate such machines - use with special care.

Caution

Experimental! User reported problems with this option.

device-id=<hex id>

Override PCI device ID visible to guest

driver=<keep | vfio> (default = vfio)

If set to keep the device will neither be reset nor bound to the vfio-pci driver. Useful for devices that already have the correct driver loaded.

host=<HOSTPCIID[;HOSTPCIID2...]>

Host PCI device pass through. The PCI ID of a host’s PCI device or a list of PCI virtual functions of the host. HOSTPCIID syntax is: bus:dev.func (hexadecimal numbers)

You can use the lspci command to list existing PCI devices.

Either this or the mapping key must be set.

legacy-igd=<boolean> (default = 0)

Pass this device in legacy IGD mode, making it the primary and exclusive graphics device in the VM. Requires pc-i440fx machine type and VGA set to none.

mapping=<mapping-id>

The ID of a cluster wide mapping. Either this or the default-key host must be set.

mdev=<string>

The type of mediated device to use. An instance of this type will be created on startup of the VM and will be cleaned up when the VM stops.

pcie=<boolean> (default = 0)

Choose the PCI-express bus (needs the q35 machine model).

rombar=<boolean> (default = 1)

Specify whether or not the device’s ROM will be visible in the guest’s memory map.

romfile=<string>

Custom pci device rom filename (must be located in /usr/share/kvm/).

sub-device-id=<hex id>

Override PCI subsystem device ID visible to guest

sub-vendor-id=<hex id>

Override PCI subsystem vendor ID visible to guest

vendor-id=<hex id>

Override PCI vendor ID visible to guest

x-vga=<boolean> (default = 0)

Enable vfio-vga device support.

hotplug: <string> (default = network,disk,usb)

Selectively enable hotplug features. This is a comma separated list of hotplug features: network, disk, cpu, memory, usb and cloudinit. Use 0 to disable hotplug completely. Using 1 as value is an alias for the default network,disk,usb. USB hotplugging is possible for guests with machine version >= 7.1 and ostype l26 or windows > 7.

hugepages: <1024 | 2 | any>

Enables hugepages memory. Sets the size of hugepages in MiB. If the value is set to any then 1 GiB hugepages will be used if possible, otherwise the size will fall back to 2 MiB.

ide[n]: [file=]<volume> [,aio=<native|threads|io_uring>] [,backup=<1|0>] [,bps=<bps>] [,bps_max_length=<seconds>] [,bps_rd=<bps>] [,bps_rd_max_length=<seconds>] [,bps_wr=<bps>] [,bps_wr_max_length=<seconds>] [,cache=<enum>] [,detect_zeroes=<1|0>] [,discard=<ignore|on>] [,format=<enum>] [,iops=<iops>] [,iops_max=<iops>] [,iops_max_length=<seconds>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_rd_max_length=<seconds>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,iops_wr_max_length=<seconds>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,model=<model>] [,replicate=<1|0>] [,rerror=<ignore|report|stop>] [,serial=<serial>] [,shared=<1|0>] [,size=<DiskSize>] [,snapshot=<1|0>] [,ssd=<1|0>] [,werror=<enum>] [,wwn=<wwn>]

Use volume as IDE hard disk or CD-ROM (n is 0 to 3). aio=<io_uring | native | threads>

AIO type to use.

backup=<boolean>

Whether the drive should be included when making backups.

bps=<bps>

Maximum r/w speed in bytes per second.

bps_max_length=<seconds>

Maximum length of I/O bursts in seconds.

bps_rd=<bps>

Maximum read speed in bytes per second.

bps_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

bps_wr=<bps>

Maximum write speed in bytes per second.

bps_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

cache=<directsync | none | unsafe | writeback | writethrough>

The drive’s cache mode

detect_zeroes=<boolean>

Controls whether to detect and try to optimize writes of zeroes.

discard=<ignore | on>

Controls whether to pass discard/trim requests to the underlying storage.

file=<volume>

The drive’s backing volume.

format=<cloop | qcow | qcow2 | qed | raw | vmdk>

The drive’s backing file’s data format.

iops=<iops>

Maximum r/w I/O in operations per second.

iops_max=<iops>

Maximum unthrottled r/w I/O pool in operations per second.

iops_max_length=<seconds>

Maximum length of I/O bursts in seconds.

iops_rd=<iops>

Maximum read I/O in operations per second.

iops_rd_max=<iops>

Maximum unthrottled read I/O pool in operations per second.

iops_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

iops_wr=<iops>

Maximum write I/O in operations per second.

iops_wr_max=<iops>

Maximum unthrottled write I/O pool in operations per second.

iops_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

mbps=<mbps>

Maximum r/w speed in megabytes per second.

mbps_max=<mbps>

Maximum unthrottled r/w pool in megabytes per second.

mbps_rd=<mbps>

Maximum read speed in megabytes per second.

mbps_rd_max=<mbps>

Maximum unthrottled read pool in megabytes per second.

mbps_wr=<mbps>

Maximum write speed in megabytes per second.

mbps_wr_max=<mbps>

Maximum unthrottled write pool in megabytes per second.

media=<cdrom | disk> (default = disk)

The drive’s media type.

model=<model>

The drive’s reported model name, url-encoded, up to 40 bytes long.

replicate=<boolean> (default = 1)

Whether the drive should considered for replication jobs.

rerror=<ignore | report | stop>

Read error action.

serial=<serial>

The drive’s reported serial number, url-encoded, up to 20 bytes long.

shared=<boolean> (default = 0)

Mark this locally-managed volume as available on all nodes.

Warning

This option does not share the volume automatically, it assumes it is shared already!

size=<DiskSize>

Disk size. This is purely informational and has no effect.

snapshot=<boolean>

Controls qemu’s snapshot mode feature. If activated, changes made to the disk are temporary and will be discarded when the VM is shutdown.

ssd=<boolean>

Whether to expose this drive as an SSD, rather than a rotational hard disk.

werror=<enospc | ignore | report | stop>

Write error action.

wwn=<wwn>

The drive’s worldwide name, encoded as 16 bytes hex string, prefixed by 0x.

intel-tdx: [type=]<tdx-type> ,attestation=<1|0> [,vsock-cid=<integer>] [,vsock-port=<integer>]

Trusted Domain Extension (TDX) features by Intel CPUs attestation=<boolean> (default = 1)

Enable TDX attestation by including quote-generation-socket

type=<tdx-type>

Enable TDX

vsock-cid=<integer> (2 - N) (default = 2)

CID for vsock of Quote Generation Service

vsock-port=<integer> (0 - N) (default = 4050)

Port for vsock of Quote Generation Service

ipconfig[n]: [gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]

cloud-init: Specify IP addresses and gateways for the corresponding interface. IP addresses use CIDR notation, gateways are optional but need an IP of the same type specified.

The special string dhcp can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided. For IPv6 the special string auto can be used to use stateless autoconfiguration. This requires cloud-init 19.4 or newer.

If cloud-init is enabled and neither an IPv4 nor an IPv6 address is specified, it defaults to using dhcp on IPv4.

gw=<GatewayIPv4>

Default gateway for IPv4 traffic.

Note

Requires option(s): ip

gw6=<GatewayIPv6>

Default gateway for IPv6 traffic.

Note

Requires option(s): ip6

ip=<IPv4Format/CIDR> (default = dhcp)

IPv4 address in CIDR format.

ip6=<IPv6Format/CIDR> (default = dhcp)

IPv6 address in CIDR format.

ivshmem: size=<integer> [,name=<string>]

Inter-VM shared memory. Useful for direct communication between VMs, or to the host. name=<string>

The name of the file. Will be prefixed with pve-shm-. Default is the VMID. Will be deleted when the VM is stopped.

size=<integer> (1 - N)

The size of the file in MB.

keephugepages: <boolean> (default = 0)

Use together with hugepages. If enabled, hugepages will not not be deleted after VM shutdown and can be used for subsequent starts.

keyboard: <da | de | de-ch | en-gb | en-us | es | fi | fr | fr-be | fr-ca | fr-ch | hu | is | it | ja | lt | mk | nl | no | pl | pt | pt-br | sl | sv | tr>

Keyboard layout for VNC server. This option is generally not required and is often better handled from within the guest OS.

kvm: <boolean> (default = 1)

Enable/disable KVM hardware virtualization.

localtime: <boolean>

Set the real time clock (RTC) to local time. This is enabled by default if the ostype indicates a Microsoft Windows OS.

lock: <backup | block | clone | create | migrate | rollback | snapshot | snapshot-delete | suspended | suspending>

Lock/unlock the VM.

machine: [[type=]<machine type>] [,aw-bits=<number>] [,enable-s3=<1|0>] [,enable-s4=<1|0>] [,viommu=<intel|virtio>]

Specify the QEMU machine. aw-bits=<number> (32 - 64)

Specifies the vIOMMU address space bit width. Intel vIOMMU supports a bit width of either 39 or 48 bits and VirtIO vIOMMU supports any bit width between 32 and 64 bits.

enable-s3=<boolean>

Enables S3 power state. Defaults to false beginning with machine types 9.2+pve1, true before.

enable-s4=<boolean>

Enables S4 power state. Defaults to false beginning with machine types 9.2+pve1, true before.

type=<machine type>

Specifies the QEMU machine type.

viommu=<intel | virtio>

Enable and set guest vIOMMU variant (Intel vIOMMU needs q35 to be set as machine type).

memory: [current=]<integer>

Memory properties. current=<integer> (16 - N) (default = 512)

Current amount of online RAM for the VM in MiB. This is the maximum available memory when you use the balloon device.

migrate_downtime: <number> (0 - N) (default = 0.1)

Set maximum tolerated downtime (in seconds) for migrations. Should the migration not be able to converge in the very end, because too much newly dirtied RAM needs to be transferred, the limit will be increased automatically step-by-step until migration can converge. Will be capped to 2000 seconds (maximum in QEMU).

migrate_speed: <integer> (0 - N) (default = 0)

Set maximum speed (in MB/s) for migrations. Value 0 is no limit.

name: <string>

Set a name for the VM. Only used on the configuration web interface.

nameserver: <string>

cloud-init: Sets DNS server IP address for a container. Create will automatically use the setting from the host if neither searchdomain nor nameserver are set.

net[n]: [model=]<enum> [,bridge=<bridge>] [,firewall=<1|0>] [,link_down=<1|0>] [,macaddr=<XX:XX:XX:XX:XX:XX>] [,mtu=<integer>] [,queues=<integer>] [,rate=<number>] [,tag=<integer>] [,trunks=<vlanid[;vlanid...]>] [,<model>=<macaddr>]

Specify network devices. bridge=<bridge>

Bridge to attach the network device to. The Proxmox VE standard bridge is called vmbr0. If you do not specify a bridge, we create a kvm user (NATed) network device, which provides DHCP and DNS services. The following addresses are used:

```
10.0.2.2   Gateway
10.0.2.3   DNS Server
10.0.2.4   SMB Server
```

The DHCP server assign addresses to the guest starting from 10.0.2.15.

firewall=<boolean>

Whether this interface should be protected by the firewall.

link_down=<boolean>

Whether this interface should be disconnected (like pulling the plug).

macaddr=<XX:XX:XX:XX:XX:XX>

A common MAC address with the I/G (Individual/Group) bit not set.

model=<e1000 | e1000-82540em | e1000-82544gc | e1000-82545em | e1000e | i82551 | i82557b | i82559er | ne2k_isa | ne2k_pci | pcnet | rtl8139 | virtio | vmxnet3>

Network Card Model. The virtio model provides the best performance with very low CPU overhead. If your guest does not support this driver, it is usually best to use e1000.

mtu=<integer> (1 - 65520)

Force MTU of network device (VirtIO only). Setting to 1 or empty will use the bridge MTU

queues=<integer> (0 - 64)

Number of packet queues to be used on the device.

rate=<number> (0 - N)

Rate limit in mbps (megabytes per second) as floating point number.

tag=<integer> (1 - 4094)

VLAN tag to apply to packets on this interface.

trunks=<vlanid[;vlanid...]>

VLAN trunks to pass through this interface.

numa: <boolean> (default = 0)

Enable/disable NUMA.

numa[n]: cpus=<id[-id];...> [,hostnodes=<id[-id];...>] [,memory=<number>] [,policy=<preferred|bind|interleave>]

NUMA topology. cpus=<id[-id];...>

CPUs accessing this NUMA node.

hostnodes=<id[-id];...>

Host NUMA nodes to use.

memory=<number>

Amount of memory this NUMA node provides.

policy=<bind | interleave | preferred>

NUMA allocation policy.

onboot: <boolean> (default = 0)

Specifies whether a VM will be started during system bootup.

ostype: <l24 | l26 | other | solaris | w2k | w2k3 | w2k8 | win10 | win11 | win7 | win8 | wvista | wxp> (default = other)

Specify guest operating system. This is used to enable special optimization/features for specific operating systems: other

unspecified OS

wxp

Microsoft Windows XP

w2k

Microsoft Windows 2000

w2k3

Microsoft Windows 2003

w2k8

Microsoft Windows 2008

wvista

Microsoft Windows Vista

win7

Microsoft Windows 7

win8

Microsoft Windows 8/2012/2012r2

win10

Microsoft Windows 10/2016/2019

win11

Microsoft Windows 11/2022/2025

l24

Linux 2.4 Kernel

l26

Linux 2.6 - 7.X Kernel

solaris

Solaris/OpenSolaris/OpenIndiania kernel

parallel[n]: /dev/parport\d+|/dev/usb/lp\d+

Map host parallel devices (n is 0 to 2).

Note

This option allows direct access to host hardware. So it is no longer possible to migrate such machines - use with special care.

Caution

Experimental! User reported problems with this option.

protection: <boolean> (default = 0)

Sets the protection flag of the VM. This will disable the remove VM and remove disk operations.

reboot: <boolean> (default = 1)

Allow reboot. If set to 0 the VM exit on reboot.

rng0: [source=]</dev/urandom|/dev/random|/dev/hwrng> [,max_bytes=<integer>] [,period=<integer>]

Configure a VirtIO-based Random Number Generator. max_bytes=<integer> (default = 1024)

Maximum bytes of entropy allowed to get injected into the guest every period milliseconds. Use 0 to disable limiting (potentially dangerous!).

period=<integer> (default = 1000)

Every period milliseconds the entropy-injection quota is reset, allowing the guest to retrieve another max_bytes of entropy.

source=</dev/hwrng | /dev/random | /dev/urandom>

The file on the host to gather entropy from. Using urandom does not decrease security in any meaningful way, as it’s still seeded from real entropy, and the bytes provided will most likely be mixed with real entropy on the guest as well. /dev/hwrng can be used to pass through a hardware RNG from the host.

sata[n]: [file=]<volume> [,aio=<native|threads|io_uring>] [,backup=<1|0>] [,bps=<bps>] [,bps_max_length=<seconds>] [,bps_rd=<bps>] [,bps_rd_max_length=<seconds>] [,bps_wr=<bps>] [,bps_wr_max_length=<seconds>] [,cache=<enum>] [,detect_zeroes=<1|0>] [,discard=<ignore|on>] [,format=<enum>] [,iops=<iops>] [,iops_max=<iops>] [,iops_max_length=<seconds>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_rd_max_length=<seconds>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,iops_wr_max_length=<seconds>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,replicate=<1|0>] [,rerror=<ignore|report|stop>] [,serial=<serial>] [,shared=<1|0>] [,size=<DiskSize>] [,snapshot=<1|0>] [,ssd=<1|0>] [,werror=<enum>] [,wwn=<wwn>]

Use volume as SATA hard disk or CD-ROM (n is 0 to 5). aio=<io_uring | native | threads>

AIO type to use.

backup=<boolean>

Whether the drive should be included when making backups.

bps=<bps>

Maximum r/w speed in bytes per second.

bps_max_length=<seconds>

Maximum length of I/O bursts in seconds.

bps_rd=<bps>

Maximum read speed in bytes per second.

bps_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

bps_wr=<bps>

Maximum write speed in bytes per second.

bps_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

cache=<directsync | none | unsafe | writeback | writethrough>

The drive’s cache mode

detect_zeroes=<boolean>

Controls whether to detect and try to optimize writes of zeroes.

discard=<ignore | on>

Controls whether to pass discard/trim requests to the underlying storage.

file=<volume>

The drive’s backing volume.

format=<cloop | qcow | qcow2 | qed | raw | vmdk>

The drive’s backing file’s data format.

iops=<iops>

Maximum r/w I/O in operations per second.

iops_max=<iops>

Maximum unthrottled r/w I/O pool in operations per second.

iops_max_length=<seconds>

Maximum length of I/O bursts in seconds.

iops_rd=<iops>

Maximum read I/O in operations per second.

iops_rd_max=<iops>

Maximum unthrottled read I/O pool in operations per second.

iops_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

iops_wr=<iops>

Maximum write I/O in operations per second.

iops_wr_max=<iops>

Maximum unthrottled write I/O pool in operations per second.

iops_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

mbps=<mbps>

Maximum r/w speed in megabytes per second.

mbps_max=<mbps>

Maximum unthrottled r/w pool in megabytes per second.

mbps_rd=<mbps>

Maximum read speed in megabytes per second.

mbps_rd_max=<mbps>

Maximum unthrottled read pool in megabytes per second.

mbps_wr=<mbps>

Maximum write speed in megabytes per second.

mbps_wr_max=<mbps>

Maximum unthrottled write pool in megabytes per second.

media=<cdrom | disk> (default = disk)

The drive’s media type.

replicate=<boolean> (default = 1)

Whether the drive should considered for replication jobs.

rerror=<ignore | report | stop>

Read error action.

serial=<serial>

The drive’s reported serial number, url-encoded, up to 20 bytes long.

shared=<boolean> (default = 0)

Mark this locally-managed volume as available on all nodes.

Warning

This option does not share the volume automatically, it assumes it is shared already!

size=<DiskSize>

Disk size. This is purely informational and has no effect.

snapshot=<boolean>

Controls qemu’s snapshot mode feature. If activated, changes made to the disk are temporary and will be discarded when the VM is shutdown.

ssd=<boolean>

Whether to expose this drive as an SSD, rather than a rotational hard disk.

werror=<enospc | ignore | report | stop>

Write error action.

wwn=<wwn>

The drive’s worldwide name, encoded as 16 bytes hex string, prefixed by 0x.

scsi[n]: [file=]<volume> [,aio=<native|threads|io_uring>] [,backup=<1|0>] [,bps=<bps>] [,bps_max_length=<seconds>] [,bps_rd=<bps>] [,bps_rd_max_length=<seconds>] [,bps_wr=<bps>] [,bps_wr_max_length=<seconds>] [,cache=<enum>] [,detect_zeroes=<1|0>] [,discard=<ignore|on>] [,format=<enum>] [,iops=<iops>] [,iops_max=<iops>] [,iops_max_length=<seconds>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_rd_max_length=<seconds>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,iops_wr_max_length=<seconds>] [,iothread=<1|0>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,product=<product>] [,queues=<integer>] [,replicate=<1|0>] [,rerror=<ignore|report|stop>] [,ro=<1|0>] [,scsiblock=<1|0>] [,serial=<serial>] [,shared=<1|0>] [,size=<DiskSize>] [,snapshot=<1|0>] [,ssd=<1|0>] [,vendor=<vendor>] [,werror=<enum>] [,wwn=<wwn>]

Use volume as SCSI hard disk or CD-ROM (n is 0 to 30). aio=<io_uring | native | threads>

AIO type to use.

backup=<boolean>

Whether the drive should be included when making backups.

bps=<bps>

Maximum r/w speed in bytes per second.

bps_max_length=<seconds>

Maximum length of I/O bursts in seconds.

bps_rd=<bps>

Maximum read speed in bytes per second.

bps_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

bps_wr=<bps>

Maximum write speed in bytes per second.

bps_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

cache=<directsync | none | unsafe | writeback | writethrough>

The drive’s cache mode

detect_zeroes=<boolean>

Controls whether to detect and try to optimize writes of zeroes.

discard=<ignore | on>

Controls whether to pass discard/trim requests to the underlying storage.

file=<volume>

The drive’s backing volume.

format=<cloop | qcow | qcow2 | qed | raw | vmdk>

The drive’s backing file’s data format.

iops=<iops>

Maximum r/w I/O in operations per second.

iops_max=<iops>

Maximum unthrottled r/w I/O pool in operations per second.

iops_max_length=<seconds>

Maximum length of I/O bursts in seconds.

iops_rd=<iops>

Maximum read I/O in operations per second.

iops_rd_max=<iops>

Maximum unthrottled read I/O pool in operations per second.

iops_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

iops_wr=<iops>

Maximum write I/O in operations per second.

iops_wr_max=<iops>

Maximum unthrottled write I/O pool in operations per second.

iops_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

iothread=<boolean>

Whether to use iothreads for this drive

mbps=<mbps>

Maximum r/w speed in megabytes per second.

mbps_max=<mbps>

Maximum unthrottled r/w pool in megabytes per second.

mbps_rd=<mbps>

Maximum read speed in megabytes per second.

mbps_rd_max=<mbps>

Maximum unthrottled read pool in megabytes per second.

mbps_wr=<mbps>

Maximum write speed in megabytes per second.

mbps_wr_max=<mbps>

Maximum unthrottled write pool in megabytes per second.

media=<cdrom | disk> (default = disk)

The drive’s media type.

product=<product>

The drive’s product name, up to 16 bytes long.

queues=<integer> (2 - N)

Number of queues.

replicate=<boolean> (default = 1)

Whether the drive should considered for replication jobs.

rerror=<ignore | report | stop>

Read error action.

ro=<boolean>

Whether the drive is read-only.

scsiblock=<boolean> (default = 0)

whether to use scsi-block for full passthrough of host block device

Warning

can lead to I/O errors in combination with low memory or high memory fragmentation on host

serial=<serial>

The drive’s reported serial number, url-encoded, up to 20 bytes long.

shared=<boolean> (default = 0)

Mark this locally-managed volume as available on all nodes.

Warning

This option does not share the volume automatically, it assumes it is shared already!

size=<DiskSize>

Disk size. This is purely informational and has no effect.

snapshot=<boolean>

Controls qemu’s snapshot mode feature. If activated, changes made to the disk are temporary and will be discarded when the VM is shutdown.

ssd=<boolean>

Whether to expose this drive as an SSD, rather than a rotational hard disk.

vendor=<vendor>

The drive’s vendor name, up to 8 bytes long.

werror=<enospc | ignore | report | stop>

Write error action.

wwn=<wwn>

The drive’s worldwide name, encoded as 16 bytes hex string, prefixed by 0x.

scsihw: <lsi | lsi53c810 | megasas | megasas-gen2 | mptsas1068 | pvscsi | virtio-scsi-pci | virtio-scsi-single> (default = lsi)

SCSI controller model

searchdomain: <string>

cloud-init: Sets DNS search domains for a container. Create will automatically use the setting from the host if neither searchdomain nor nameserver are set.

serial[n]: (/dev/[^,]+|socket)

Create a serial device inside the VM (n is 0 to 3), and pass through a host serial device (i.e. /dev/ttyS0), or create a unix socket on the host side (use qm terminal to open a terminal connection).

Note

If you pass through a host serial device, it is no longer possible to migrate such machines - use with special care.

Caution

Experimental! User reported problems with this option.

shares: <integer> (0 - 50000) (default = 1000)

Amount of memory shares for auto-ballooning. The larger the number is, the more memory this VM gets. Number is relative to weights of all other running VMs. Using zero disables auto-ballooning. Auto-ballooning is done by pvestatd.

smbios1: [base64=<1|0>] [,family=<Base64 encoded string>] [,manufacturer=<Base64 encoded string>] [,product=<Base64 encoded string>] [,serial=<Base64 encoded string>] [,sku=<Base64 encoded string>] [,uuid=<UUID>] [,version=<Base64 encoded string>]

Specify SMBIOS type 1 fields. base64=<boolean>

Flag to indicate that the SMBIOS values are base64 encoded

family=<Base64 encoded string>

Set SMBIOS1 family string.

manufacturer=<Base64 encoded string>

Set SMBIOS1 manufacturer.

product=<Base64 encoded string>

Set SMBIOS1 product ID.

serial=<Base64 encoded string>

Set SMBIOS1 serial number.

sku=<Base64 encoded string>

Set SMBIOS1 SKU string.

uuid=<UUID>

Set SMBIOS1 UUID.

version=<Base64 encoded string>

Set SMBIOS1 version.

smp: <integer> (1 - N) (default = 1)

The number of CPUs. Please use option -sockets instead.

sockets: <integer> (1 - N) (default = 1)

The number of CPU sockets.

spice_enhancements: [foldersharing=<1|0>] [,videostreaming=<off|all|filter>]

Configure additional enhancements for SPICE. foldersharing=<boolean> (default = 0)

Enable folder sharing via SPICE. Needs Spice-WebDAV daemon installed in the VM.

videostreaming=<all | filter | off> (default = off)

Enable video streaming. Uses compression for detected video streams.

sshkeys: <string>

cloud-init: Setup public SSH keys (one key per line, OpenSSH format).

startdate: (now | YYYY-MM-DD | YYYY-MM-DDTHH:MM:SS) (default = now)

Set the initial date of the real time clock. Valid format for date are:'now' or 2006-06-17T16:01:21 or 2006-06-17.

startup: `[[order=]\d+] [,up=\d+] [,down=\d+] `

Startup and shutdown behavior. Order is a non-negative number defining the general startup order. Shutdown in done with reverse ordering. Additionally you can set the up or down delay in seconds, which specifies a delay to wait before the next VM is started or stopped.

tablet: <boolean> (default = 1)

Enable/disable the USB tablet device. This device is usually needed to allow absolute mouse positioning with VNC. Else the mouse runs out of sync with normal VNC clients. If you’re running lots of console-only guests on one host, you may consider disabling this to save some context switches. This is turned off by default if you use spice (qm set <vmid> --vga qxl).

tags: <string>

Tags of the VM. This is only meta information.

tdf: <boolean> (default = 0)

Enable/disable time drift fix.

template: <boolean> (default = 0)

Enable/disable Template.

tpmstate0: [file=]<volume> [,format=<raw|qcow2|vmdk>] [,size=<DiskSize>] [,version=<v1.2|v2.0>]

Configure a Disk for storing TPM state. The format is fixed to raw. file=<volume>

The drive’s backing volume.

format=<qcow2 | raw | vmdk>

Format of the image.

size=<DiskSize>

Disk size. This is purely informational and has no effect.

version=<v1.2 | v2.0> (default = v1.2)

The TPM interface version. v2.0 is newer and should be preferred. Note that this cannot be changed later on.

unused[n]: [file=]<volume>

Reference to unused volumes. This is used internally, and should not be modified manually. file=<volume>

The drive’s backing volume.

usb[n]: [[host=]<HOSTUSBDEVICE|spice>] [,mapping=<mapping-id>] [,usb3=<1|0>]

Configure an USB device (n is 0 to 4, for machine version >= 7.1 and ostype l26 or windows > 7, n can be up to 14). host=<HOSTUSBDEVICE|spice>

The Host USB device or port or the value spice. HOSTUSBDEVICE syntax is:

```
'bus-port(.port)*' (decimal numbers) or
'vendor_id:product_id' (hexadecimal numbers) or
'spice'
```

You can use the lsusb -t command to list existing usb devices.

Note

This option allows direct access to host hardware. So it is no longer possible to migrate such machines - use with special care.

The value spice can be used to add a usb redirection devices for spice. Either this or the mapping key must be set.

mapping=<mapping-id>

The ID of a cluster wide mapping. Either this or the default-key host must be set.

usb3=<boolean> (default = 0)

Specifies whether if given host option is a USB3 device or port. For modern guests (machine version >= 7.1 and ostype l26 and windows > 7), this flag is irrelevant (all devices are plugged into a xhci controller).

vcpus: <integer> (1 - N) (default = 0)

Number of hotplugged vcpus.

vga: [[type=]<enum>] [,clipboard=<vnc>] [,memory=<integer>]

Configure the VGA Hardware. If you want to use high resolution modes (>= 1280x1024x16) you may need to increase the vga memory option. Since QEMU 2.9 the default VGA display type is std for all OS types besides some Windows versions (XP and older) which use cirrus. The qxl option enables the SPICE display server. For win* OS you can select how many independent displays you want, Linux guests can add displays them self. You can also run without any graphic card, using a serial device as terminal. clipboard=<vnc>

Enable a specific clipboard. If not set, depending on the display type the SPICE one will be added. Live migration with a VNC clipboard is not possible with QEMU machine version < 10.1.

memory=<integer> (4 - 512)

Sets the VGA memory (in MiB). Has no effect with serial display.

type=<cirrus | none | qxl | qxl2 | qxl3 | qxl4 | serial0 | serial1 | serial2 | serial3 | std | virtio | virtio-gl | vmware> (default = std)

Select the VGA type. Using type cirrus is not recommended.

virtio[n]: [file=]<volume> [,aio=<native|threads|io_uring>] [,backup=<1|0>] [,bps=<bps>] [,bps_max_length=<seconds>] [,bps_rd=<bps>] [,bps_rd_max_length=<seconds>] [,bps_wr=<bps>] [,bps_wr_max_length=<seconds>] [,cache=<enum>] [,detect_zeroes=<1|0>] [,discard=<ignore|on>] [,format=<enum>] [,iops=<iops>] [,iops_max=<iops>] [,iops_max_length=<seconds>] [,iops_rd=<iops>] [,iops_rd_max=<iops>] [,iops_rd_max_length=<seconds>] [,iops_wr=<iops>] [,iops_wr_max=<iops>] [,iops_wr_max_length=<seconds>] [,iothread=<1|0>] [,mbps=<mbps>] [,mbps_max=<mbps>] [,mbps_rd=<mbps>] [,mbps_rd_max=<mbps>] [,mbps_wr=<mbps>] [,mbps_wr_max=<mbps>] [,media=<cdrom|disk>] [,replicate=<1|0>] [,rerror=<ignore|report|stop>] [,ro=<1|0>] [,serial=<serial>] [,shared=<1|0>] [,size=<DiskSize>] [,snapshot=<1|0>] [,werror=<enum>]

Use volume as VIRTIO hard disk (n is 0 to 15). aio=<io_uring | native | threads>

AIO type to use.

backup=<boolean>

Whether the drive should be included when making backups.

bps=<bps>

Maximum r/w speed in bytes per second.

bps_max_length=<seconds>

Maximum length of I/O bursts in seconds.

bps_rd=<bps>

Maximum read speed in bytes per second.

bps_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

bps_wr=<bps>

Maximum write speed in bytes per second.

bps_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

cache=<directsync | none | unsafe | writeback | writethrough>

The drive’s cache mode

detect_zeroes=<boolean>

Controls whether to detect and try to optimize writes of zeroes.

discard=<ignore | on>

Controls whether to pass discard/trim requests to the underlying storage.

file=<volume>

The drive’s backing volume.

format=<cloop | qcow | qcow2 | qed | raw | vmdk>

The drive’s backing file’s data format.

iops=<iops>

Maximum r/w I/O in operations per second.

iops_max=<iops>

Maximum unthrottled r/w I/O pool in operations per second.

iops_max_length=<seconds>

Maximum length of I/O bursts in seconds.

iops_rd=<iops>

Maximum read I/O in operations per second.

iops_rd_max=<iops>

Maximum unthrottled read I/O pool in operations per second.

iops_rd_max_length=<seconds>

Maximum length of read I/O bursts in seconds.

iops_wr=<iops>

Maximum write I/O in operations per second.

iops_wr_max=<iops>

Maximum unthrottled write I/O pool in operations per second.

iops_wr_max_length=<seconds>

Maximum length of write I/O bursts in seconds.

iothread=<boolean>

Whether to use iothreads for this drive

mbps=<mbps>

Maximum r/w speed in megabytes per second.

mbps_max=<mbps>

Maximum unthrottled r/w pool in megabytes per second.

mbps_rd=<mbps>

Maximum read speed in megabytes per second.

mbps_rd_max=<mbps>

Maximum unthrottled read pool in megabytes per second.

mbps_wr=<mbps>

Maximum write speed in megabytes per second.

mbps_wr_max=<mbps>

Maximum unthrottled write pool in megabytes per second.

media=<cdrom | disk> (default = disk)

The drive’s media type.

replicate=<boolean> (default = 1)

Whether the drive should considered for replication jobs.

rerror=<ignore | report | stop>

Read error action.

ro=<boolean>

Whether the drive is read-only.

serial=<serial>

The drive’s reported serial number, url-encoded, up to 20 bytes long.

shared=<boolean> (default = 0)

Mark this locally-managed volume as available on all nodes.

Warning

This option does not share the volume automatically, it assumes it is shared already!

size=<DiskSize>

Disk size. This is purely informational and has no effect.

snapshot=<boolean>

Controls qemu’s snapshot mode feature. If activated, changes made to the disk are temporary and will be discarded when the VM is shutdown.

werror=<enospc | ignore | report | stop>

Write error action.

virtiofs[n]: [dirid=]<mapping-id> [,cache=<enum>] [,direct-io=<1|0>] [,expose-acl=<1|0>] [,expose-xattr=<1|0>]

Configuration for sharing a directory between host and guest using Virtio-fs. cache=<always | auto | metadata | never> (default = auto)

The caching policy the file system should use (auto, always, metadata, never).

direct-io=<boolean> (default = 0)

Honor the O_DIRECT flag passed down by guest applications.

dirid=<mapping-id>

Mapping identifier of the directory mapping to be shared with the guest. Also used as a mount tag inside the VM.

expose-acl=<boolean> (default = 0)

Enable support for POSIX ACLs (enabled ACL implies xattr) for this mount.

expose-xattr=<boolean> (default = 0)

Enable support for extended attributes for this mount.

vmgenid: <UUID> (default = 1 (autogenerated))

The VM generation ID (vmgenid) device exposes a 128-bit integer value identifier to the guest OS. This allows to notify the guest operating system when the virtual machine is executed with a different configuration (e.g. snapshot execution or creation from a template). The guest operating system notices the change, and is then able to react as appropriate by marking its copies of distributed databases as dirty, re-initializing its random number generator, etc. Note that auto-creation only works when done through API/CLI create or update methods, but not when manually editing the config file.

vmstatestorage: <storage ID>

Default storage for VM state volumes/files.

watchdog: [[model=]<i6300esb|ib700>] [,action=<enum>]

Create a virtual hardware watchdog device. Once enabled (by a guest action), the watchdog must be periodically polled by an agent inside the guest or else the watchdog will reset the guest (or execute the respective action specified) action=<debug | none | pause | poweroff | reset | shutdown>

The action to perform if after activation the guest fails to poll the watchdog in time.

model=<i6300esb | ib700> (default = i6300esb)

Watchdog type to emulate.

## COPYRIGHT AND DISCLAIMER
Copyright © 2007-2022 Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/

## AUTHOR
Proxmox Server Solutions Gmbh

www.proxmox.com


policyd-spf.conf

package: pypolicyd-spf

title: policyd-spf.conf(5)

text:
# policyd-spf.conf(5)

## NAME
policyd-spf - policyd-spf python configuration parameters

## VERSION
2.0.0

## USAGE
Usage:

policyd-spf [/etc/postfix-policyd-spf-python/policyd-spf.conf]

## OTHER DOCUMENTATION
This documentation assumes you have read Postfix's README_FILES/ SMTPD_POLICY_README and are generally familiar with Sender Policy Framework (SPF). See RFC 7208 for details.

man 1 policyd-spf provides general operation documentation for this package.

man 5 policyd-spf.peruser provides documentation on setting up and using different configuration options on a per user (mail reciepient) basis.

## SYNOPSIS
python-policyd-spf operates with a default installed configuration file and set of default configuration options that are used if the configuration file cannot be found. These options can be changed by changing the installed configuration files or through giving a path to an alternate configuration file.

## DESCRIPTION
Configuration options are described here and in the configuration file provided with the package. The provided setup.py installs this configuration file in /etc/postfix-policyd-spf-python/.

Additionally, whitelisting certain IP addresses from SPF checks is supported. This man page and the sample configuration file show the format to use. These options can be adjusted on a per user (mail recipient) basis. Details on per user settings can be found in policyd-spf.peruser(5).

## LOGGING
"debugLevel" controls the amount of information logged by the policy server.

The default, 1, logs no debugging messages, just basic policy results and errors generated through the policy server. This value can be increased up to 5 (values higher than 5 will not cause an error, but will not log any additional information).

debug level 2 adds a log message if no client address (IP address from which the connection was made), Mail From address, or HELO/EHLO name is received by the policy server, and logs SPF results for each Mail From and HELO check.

debug level 3 generates a log message each time the policy server starts and each time it exits, as well as logging a copy of the exact header returned to Postfix to be prepended into the message. Each time the policy server starts, debug level 3 also logs the configuration information used by the policy server.

debug level 4 logs the complete data set received by Postfix via the policy interface and when the end of the entry is read.

debug level 5 is used to debug config file processing and, for this purpose, can only be set in code and not via the config file. It also provides additional internal status details generally of interest only to developers.

If debug level is 0, then the policy server logs errors only.

When set to -1, nothing is logged once the configuration file has been read in, not even error messages. Use with caution.

Default:

debugLevel = 1

## TEST OPERATION
The policy server can operate in a test only mode. This allows you to see the potential impact of SPF checking in your mail logs without rejecting mail. Headers are prepended in messages, but message delivery is not affected. This mode is not enabled by default. To enable it, set TestOnly = 0.

Note: This option was previously named defaultSeedOnly. This is still accepted, but logs an error.

Default:

TestOnly = 1

## HELO/EHLO CHECKING
HELO check rejection policy options are:

Fail - (Default) Reject only on HELO Fail. HELO/EHLO is known first in the SMTP dialogue and there is no practical reason to waste resources on Mail From checks if the HELO check will already cause the message to be rejected. This should not cause interoperability problems when used for HELO.

SPF_Not_Pass - Reject if result not Pass, None, or Temperror (alternatively put, reject if the SPF result is Fail, Softfail, Neutral, PermError). Unlike Mail From checking, there are no standard e-mail use cases where a HELO check should not Pass if there is an SPF record for the HELO name (transparent forwarding, for example, is not an issue). HELO/EHLO is known first in the SMTP dialogue and there is no practical reason to waste resources on Mail From checks if the HELO check will already cause the message to be rejected. This is not consistent with the RFC 7208 requirement to treat none and neutral the same, but should not cause interoperability problems when used for HELO.

Softfail - Reject on HELO Softfail or Fail. HELO/EHLO is known first in the SMTP dialogue and there is no practical reason to waste resources on Mail From checks if the HELO check will already cause the message to be rejected. This should not cause interoperability problems when used for HELO.

Null - Only reject HELO Fail for Null sender (SPF Classic). This is the approach used by the pre-RFC 4408 reference implementation and many of the pre- RFC specifications. Use of at least this option (SPF_Not_Pass or Fail) are preferred) is highly recommended.

False - Never reject on HELO, append header only. This is useful for post-SMTP spam filters such as SpamAssassin.

No_Check - Never check HELO. This is only recommended if you are calling the policy server twice (once for HELO checks and once for Mail From) with two different configuration files. This approach is useful to get both the HELO and Mail From headers prepended to a message.

Default:

HELO_reject = Fail

## HELO/EHLO PASS RESTRICTION
HELO Pass Restriction allows integration with other Postfix access controls by provding a user supplied name of a postfix access restriction to be applied to a message when the HELO checking result is Pass. The indicated restriction must be an action as defined for a Postfix SMTP server access table access(5) and explained in the Postfix RESTRICTION CLASS README. The README.per_user_whitelisting file provided with this distribution provides examples. Note: A helo pass restriction will be the returned result even if the mail from result would cause the message to be rejected.

Example:

HELO_pass_restriction = helo_passed_spf

Default:

None

## Mail From CHECKING
Mail From rejection policy options are:

SPF_Not_Pass - Reject if result not Pass/None/Tempfail. This option is not RFC 7208 compliant since the mail with an SPF Neutral result is treated differently than mail with no SPF record and Softfail results are not supposed to cause mail rejection. Global use of this option is not recommended. Use per-domain if needed (per-domain usage described below).

Softfail - Reject on Mail From Softfail or Fail. Global use of this option is not recommended. Use per-domain if needed (per-domain usage described below).

Fail (default) - Reject on Mail From Fail.

False - Never reject on Mail From, append header only. This is useful for post-SMTP spam filters such as SpamAssassin.

No_Check - Never check Mail From/Return Path. This is only recommended if you are calling the policy server twice (once for HELO checks and once for Mail From) with two different configuration files. This approach is useful to get both the HELO and Mail From headers prepended to a message. It could also be used to do HELO checking only (because HELO checking has a lower false positive risk than Mail From checking), but this approach may not be fully RFC 7208 compliant since the Mail From identity is mandatory if HELO checking does not reach a definitive result.

Default:

Mail_From_reject = Fail

## Mail From PASS RESTRICTION
Mail From Pass Restriction allows integration with other Postfix access contlols by provding a user supplied name of a postfix access restriction to be applied to a message when the Mail From checking result is Pass. The indicated restriction must be an action as defined for a Postfix SMTP server access table access(5) and explained in the Postfix RESTRICTION CLASS README. The README.per_user_whitelisting file provided with this distribution provides examples. Note: A mail from pass restriction will be the returned result even if the helo result would cause the message to be rejected.

Example:

Mail_From_pass_restriction = mfrom_passed_spf

Default:

None

## Limit Rejections To Domains That Send No Mail
No_Mail - Only reject when SPF indicates the host/domain sends no mail. This option will only cause mail to be rejected if the HELO/Mail From record is "v=spf1 -all". This option is useful for rejecting mail in situations where the tolerance for rejecting wanted mail is very low. It operates on both HELO and Mail From identities if set.

Default:

No_Mail = False

## Domain Specific Receiver Policy
Using this option, a list of domains can be defined for special processing when messages do not Pass SPF. This can be useful for commonly spoofed domains that are not yet publishing SPF records with -all. Specifically, if mail from a domain in this list has a Neutral/Softfail result, it will be rejected (as if it had a Fail result). If needed, it is better to do it on a per-domain basis rather than globally.

Example:

Reject_Not_Pass_Domains = aol.com,hotmail.com

Default:

None

## Permanent Error Processing
Policy for rejecting due to SPF PermError options are:

True - Reject the message if the SPF result (for HELO or Mail From) is PermError. This has a higher short-term false positive risk, but does result in senders getting feedback that they have a problem with their SPF record.

False - Treat PermError the same as no SPF record at all. This is consistet with the pre-RFC usage (the pre-RFC name for this error was "Unknown").

This is a global option that affects both HELO and Mail From scopes when checks for that scope are enabled. The only per scope setting that can over-ride this is Mail_From/HELO_reject = False/

Default:

PermError_reject = False

## Temporary Error Processing
Policy for deferring messages due to SPF TempError options are:

True - Defer the message if the SPF result (for HELO or Mail From) is TempError. This is the traditional usage and has proven useful in reducing acceptance of unwanted messages. Sometimes spam senders do not retry. Sometimes by the time a message is retried the sending IP has made it onto a DNS RBL and can then be rejected. This is not the default because it is possible for some DNS errors that are classified as "Temporary" per RFC 7208 to be permanent in the sense that they require operator intervention to correct.

This is a global option that affects both HELO and Mail From scopes when checks for that scope are enabled. The only per scope setting that can over-ride this is Mail_From/HELO_reject = False/

False - Treat TempError the same as no SPF record at all. This is the default to minimize false positive risk.

Default:

TempError_Defer = False

## Prospective SPF Check
Prospective SPF checking - Check to see if mail sent from the defined IP address would pass. This is useful for outbound MTAs to avoid sending mail that would Fail SPF checks when received. Disable HELO checking when using this option. It's only potentially useful for Mail From checking. SPF Received headers are not added when this option is used.

Prospective = 192.168.0.4

Default:

None

## LOCAL SPF BYPASS LIST
Do not check SPF for localhost addresses - add to skip addresses to skip SPF for internal networks if desired. Defaults are standard IPv4 and IPv6 localhost addresses. This can also be used, to allow mail from local clients submitting mail to an MTA also acting as a Mail Submission Agent (MSA) to be skipped. An x-header is prepended indicating SPF checks were skipped due to a local address. This is a trace header only. Note the lack of spaces in the list.

Default:

skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1

## SPF IP WHITELIST
A comma separated CIDR Notation list of IP addresses to skip SPF checks for. Use this list to whitelist trusted relays (such as a secondary MX and trusted forwarders). An x-header is prepended indicating the IP was whitelisted against SPF checks. This is a trace header only. Note the lack of spaces in the list.

Example:

Whitelist = 192.168.0.0/31,192.168.1.0/30

Default:

None

## SPF HELO WHITELIST
A comma separated HELO/EHLO host names to skip SPF checks for. Use this list to whitelist trusted relays (such as a secondary MX and trusted forwarders) or to work around a host with a buggy SPF record. An x-header is prepended indicating the host was whitelisted against SPF checks. This is a trace header only. Note the lack of spaces in the list.

This option includes a check to ensure the connect IP address is referenced in an A or AAAA record by the HELO/EHLO domain that is whitelisted. This is to avoid inadvertent bypass of SPF checks if HELO/EHLO names are forged. If a HELO/EHLO domain is unable to pass such a forward IP address match check, then use an SPF IP Whitelist for the host's IP address instead.

Example:

HELO_Whitelist = relay.example.com,sender.example.org

Default:

None

## SPF DOMAIN WHITELIST
Domain_Whitelist: List of domains whose sending IPs should be whitelisted from SPF checks. Use this to list trusted forwarders by domain name. Client IP addresses are tested against SPF records published by the listed domains. This is useful for large forwarders with complex outbound infrastructures and SPF records. This option is less scalable than the SPF IP Whitelist. An x-header is prepended indicating the IP was whitelisted against SPF checks. This is a trace header only. This option does nothing if the domain does not have an SPF record. In this case use the SPF IP Whitelist described above or Domain_Whitelist_PTR (below). Note the lack of spaces in the list.

Example:

Domain_Whitelist = pobox.com,trustedforwarder.org

Default:

None

## PTR DOMAIN WHITELIST
Domain_Whitelist_PTR: List of domains (and subdomains) whose sending IPs should be whitelisted from SPF checks based on PTR match of the domain. Use this to list trusted forwarders by domain name if they do not publish SPF records. Client IP addresses PTR names are tested to see if they match the listed domains. This is useful for large forwarders with complex outbound infrastructures, but no SPF records and predictable host naming. Matching is done using the same rules as the SPF PTR mechanism as described in RFC 7208. List the parent domain and all subdomains will match. This option is less scalable than the SPF IP Whitelist. An x-header is prepended indicating the IP was whitelisted against SPF checks. This is a trace header only. This option does nothing if the host does not have a PTR record record. In this case use the SPF IP Whitelist described above. Note the lack of spaces in the list.

Example:

Domain_Whitelist_PTR = yahoo.com,yahoogroups.com

Default:

None

## SPF ENHANCED STATUS CODES
By default, Postfix will use the 4/5.7.1 enhanced status code for defer/reject actions from the policy server (originally defined in RFC 1893, RFC 3463 is the current reference). New email authentication (including SPF) specific codes were defined in RFC 7372. The policy server now overrides the Postfix enhanced status codes to use the RFC 7372 values. This can be disabled by setting this option to "No" in the event of interoperability issues.

Example:

SPF_Enhanced_Status_Codes = No

Default:

Yes

## RESULTS HEADER
The standard method for documenting SPF results in a message (for consumption by downstream processes) is the Received-SPF header defined in RFC 7208. This is the default header to use. Results can also be documented in the Authentication-Results header, which is also covered in RFC 7208. The default is Received-SPF (SPF), but inclusion of Authentication-Results (AR) headers as an alternative to Received-SPF can be specified.

If there is a requirement to prepend both Received-SPF and Authentication- Results headers, then it must be done by processing the message with more than one instance of the policy server using different configuration files with different Header_Type settings.

For no header at all, use Header_Type = None.

Examples:

Header_Type = SPF or Header_Type = AR

Default:

SPF

## HIDE RCPT TO IN RESULTS HEADER
Both Received-SPF and Authentication-Results (AR) header fields include the receiving (RCPT TO) address. In this application, it will always be the first recipient sent by the sending MTA, even if that recipient is a BCC recipient. This is unavoidable as the Postfix policy interface does not provide any indication that if the recipient is BCC or not (this information is not available in until after SMTP DATA in the body of the message). This presents a possible avenue for a privacy breach.

In order to avoid this, Hide_Receiver is set to Yes by default in the interest of maximizing privacy. This setting will replace the actual recipient with <UNKNOWN> both in header fields and SMTP responses. The latter may make it more difficult for senders to troubleshoot issues with their SPF deployments. As an implementation detail, currently specifying any value other than No will result in the recipient being hidden, but that may change in the future.

Examples:

Hide_Receiver = Yes or Hide_Receiver = No

Default:

True

## Authentications Results Authentication Identifier
Every Authentication-Results header field has an authentication identifier field ('Authserv_Id'). This is similar in syntax to a fully-qualified domain name. See policyd-spf.conf.5 and RFC 7001 paragraph 2.4 for details. Default is HOSTNAME. The results of socket.gethostname will be used unless an alternate value is specified. An Authserv-Id must be provided if Header_Type 'AR' is used.

The authentication identifier field provides a unique identifier that refers to the authenticating service within a given administrative domain. The identifier MUST be unique to that domain. This identifier is intended to be machine-readable and not necessarily meaningful to users.

Example:

Authserv_Id = mx.example.com

Default:

HOSTNAME

## DNS Timeout Limit
RFC 7208 recommends an elapsed time limit for SPF checks of at least 20 seconds. Lookup_Time allows the maximum time (seconds) to be adjusted. 20 seconds is the default. This limit is applied separately to Mail From and HELO/EHLO checks, so if both are performed, the lookups may take up to twice Lookup_Time (plus any additional time required for whitelisting related DNS lookups).

Example:

Lookup_Time = 20

Default

20 (seconds)

## Whitelist DNS Timeout Limit
Some of the available whitelisting mechanisms, i.e. Domain_Whitelist, Domain_Whitelist_PTR, and HELO_Whitelist, require specific non-SPF DNS lookups to determine if a connection should be white listed from SPF checks. The maximum amount of time (in seconds) allocated for each of these checks, when used (none are enabled by default), is controlled by the Whitelist_Lookup_Time parameter. It defaults to 10 seconds and is applied independently to each whitelisting method in use (e.g. if both a Domain_Whitelist_PTR and HELO_Whitelist are defined, together they may take up to 20 seconds). This is in addition to the time allowed for SPF Lookup_Time.

Example:

Whitelist_Lookup_Time = 10

Default

10 (seconds)

## DNS Void Lookup Limit
RFC 7208 adds a new processing limit called "void lookup limit" (See section 4.6.4). Void lookups are DNS queries within an SPF record for which DNS queries return either a positive answer (RCODE 0) with an answer count of 0, or a "Name Error" (RCODE 3) answer. This should not need to be changed. Although new in an RFC in RFC 7208, this limit has been widely deployed in the Mail::SPF perl library without issue. Default is 2, but it can be adjusted.

Example:

Void_Limit = 2

Default

2

## Mock SPF Check To Add Milter Compatibility Header Field
In some versions of postfix, for bizarre Sendmail compatibility reasons, the first header field added by a policy server is not visible to milters. To make this easy to work around, set the Mock value to true and a fixed header field will be inserted so the actual SPF check will be the second field and visible to milters such as DMARC milter.

To use this feature requires additional postfix configuration to execute the second, mock, instance of the policy server:

Add a second service to /etc/postfix/master.cf:

policyd-spf-mock unix - n n - 0 spawn

user=nobody argv=/usr/bin/policyd-spf '/etc/pypolicyd-spf/mock

Configure the Postfix additional policy service in /etc/postfix/main.cf to run before the regular service:

smtpd_recipient_restrictions =

...

reject_unauth_destination

check_policy_service unix:private/policyd-spf-mock

check_policy_service unix:private/policyd-spf

...

Create the specified configuration file in the location indicated with Mock set to True.

Example:

Mock = True

Default

False

## Reason Message
If a message is rejected or deferred because of the SPF policy, a reason is given for logging and debugging purposes. The String configured supports the following format specifiers:

rejectdefer - either the string 'rejected' or 'deferred' spf - SPF result code

url - Parameterized URL to http://www.openspf.net/ explaining SPF

Example:

Reason_Message = Message {rejectdefer} due to: {spf}.

Default:

Reason_Message = Message {rejectdefer} due to: {spf}. Please see {url}

## SEE ALSO
man 1 policyd-spf, man 5 policyd-spf.peruser, python-spf, <http://www.openspf.net>, RFC 7208, RFC 7001, RFC 7372

## AUTHORS
This version of policyd-spf was written by Copyright © 2007-2016, Scott Kitterman <scott@kitterman.com>. It is derived from Tumgreyspf, written by Sean Reifschneider, tummy.com, ltd <jafo@tummy.com>. Portions of the documentation were written by Meng Weng Wong <mengwong@pobox.com>.

This man-page was created by Scott Kitterman <scott@kitterman.com> and is licensed under the same terms as the program.


policyd-spf.peruser

title: policyd-spf.peruser(5)

text:
# policyd-spf.peruser(5)

## NAME
policyd-spf - policyd-spf python per-user configuration

## VERSION
2.0.0

## USAGE
Usage:

policyd-spf [/etc/policyd-spf/policyd-spf.conf]

## OTHER DOCUMENTATION
This documentation assumes you have read Postfix's README_FILES/ SMTPD_POLICY_README and are generally familiar with Sender Policy Framework (SPF). See RFC 7208 for details.

man 1 policyd-spf provides general operation documentation for this package.

See man 5 policyd-spf.conf for configuration file information.

## SYNOPSIS
python-policyd-spf operates with a default installed configuration file and set of default configuration options that are used if the configuration file cannot be found. These options can be changed by changing the installed configuration files or through giving a path to an alternate configuration file.

Additionally, different configurations can be provided on a per user basis. This man page describes setup and user of per user (mail recipient) configurations. Currently these configurations can only be stored in a text file. If there is sufficient interest, other data storage methods may be supported in the future.

## DESCRIPTION
Use of per-user configuration is defined in the application configuration file with the setting "Per_User". The value of the setting gives the type and location of the per-user configuration information. Currently supported types is text. User is defined an email address of a recipient of the message.

Most options available at the application level (See man 5 policyd-spf.conf) can be adjusted on a per-user basis. Per-user checks can only be done as part of smtpd_recipient_restrictions. Per-user actions are not possible at other stages of the SMTP dialogue. The user is not yet known for smtpd_client_restrictions, smtpd_helo_restrictions, or smtpd_sender_restrictions. If used during smtpd_data_restrictions or smtpd_end_of_data_restrictions, the entire message will be available only if the message was only to a single recipient. If per-user configurations are used when recipient information is not available, warnings will be logged and the per-user information will be ignored.

The following options cannot be modified on a per user basis: Lookup_Time, Header_Type, Hide_Receiver, Authserv_Id, Prospective, debugLevel, and Mock.

In addition to specifying individual users, regular expression matching is also available, but may have performance implications since the entire user table has to be traversed for each message recipient.

## Text Per-User Configuration File
The text file option is useful for testing and when only a small number of users require per-user configurations. It is specified in the main configuration file:

"Per_User = text,/etc/pypolicyd-spf/userconf"

Lines beginning with "#" are treated as comments and ignored. The location of the file is determined by the system administrator. No default file is provided in or installed by the package.

The configuration of the file is a comma separated combination of user and configuration information, with one line per user's configuration information (NOTE: due to man page formatting requirements, these lines may be wrapped in your pager - in the config file, it must be one line per user):

postmaster@example.com,Mail_From_reject=No_Check|PermError_reject=False|HELO_reject=SPF_Not_Pass|TestOnly=1|debugLevel=5|skip_addresses=127.0.0.0/8,::ffff:127.0.0.0//104,::1//128|TempError_Defer=False strict@example.com,PermError_reject=True|HELO_reject=SPF_Not_Pass|TempError_Defer=True

It is not necessary to specify all configuration parameters for each user, only those that are different than the overall configuration need to be specified.

If the specified per user configuration file is missing, an error is logged and the global configuration is used instead.

## SEE ALSO
man 1 policyd-spf, man 5 policyd-spf.conf, python-spf, <http://www.openspf.org>, RFC 7208

## AUTHORS
This version of policyd-spf was written by Copyright © 2007-2016, Scott Kitterman <scott@kitterman.com>. It is derived from Tumgreyspf, written by Sean Reifschneider, tummy.com, ltd <jafo@tummy.com>.

This man-page was created by Scott Kitterman <scott@kitterman.com> and is licensed under the same terms as the program.


pybugz.d

title: pybugz.d(5)

text:
# pybugz.d(5)

## NAME
pybugz.d - configuration files for pybugz

## SYNOPSIS
/usr/share/pybugz.d/*.conf

/etc/pybugz.d/*.conf

~/.bugzrc

## DESCRIPTION
When started, bugz reads configuration files from all of the locations listed above, in the order listed. In the directories, it reads the files in lexical order.

Files located in /usr/share/pybugz.d/*.conf are provided by pybugz and should not be modified.

Files located in /etc/pybugz.d/*.conf, if it exists, are provided by the system administrator.

The final file that is read, if it exists, is ~/.bugzrc by default. This is the user-specific configuration file. This file name can be overridden on the command line by using the --config-file option.

## CONFIGURATION FILE FORMAT
A configuration file consists of sections which define parameters for the Bugzillas you intend to use. Each section starts with a case-sensitive section name in square brackets and is followed by the settings, in the form "key = value" or "key : value", which define the parameters for this bugzilla instance.

The section name is also the name that should be used with the --connection option of the bugz command or the "connection" setting in the default section of the configuration file.

The section named [default] is special. Any settings defined in this section will have the value they are given here in all other sections unless they are overridden. So, for example, if you want to use the same username for most of your bugzillas, define user in the default section.

Comments are also allowed. A comment must begin with "#" or ";" and be on a line of its own.

## CONFIGURATION SETTINGS
This is a list of the current settings supported by pybugz.

connection = sectionname

This is used in the default section to define the bugzilla you connect with most of the time. It is not an error to put it in another section, but it does not make much sense to do so.

base = http://my.project.com/bugzilla/xmlrpc.cgi

base = http://myhttpname:myhttppasswd@my.project.com/bugzilla/xmlrpc.cgi

This is the base URL of the bugzilla. It must point to the xmlrpc.cgi script on the bugzilla installation. The second form is used if you need to encode a username and password into the URL for basic http authentication.

user = myname@my.project.com

password = secret2

These set your username and password for this bugzilla. If you do not provide one or both of these and you do not use the key setting below, you will be prompted for the setting you do not provide.

passwordcmd = gpg --decrypt ~/.my-encrypted-password.gpg

As another alternative for storing your password, you can provide a password command. This command will be run, and pybugz expects it to output the password to stdout. The example above uses gpg to decrypt an encrypted password stored in a file. The default setting is undefined, so it will not be used unless you define it.

key = string

This is your API key, which is an alternative way to authenticate for Bugzilla 5.0 and newer. To use this, you must generate an API key in the preferences section of Bugzilla and set it to that value. This overrides the username and password settings. The default is undefined.

columns = 80

This is the number of columns your terminal can display. Most of the time, pybugz should be able to determine this value. If it cannot, the default value is 80, so more than likely you will never have to change this setting.

debug = 0

This sets the level of debug logging. This is mostly used for development purposes. It causes PyBugz to print out debugging information as it runs.

quiet = False

If set to true, this requests that pybugz run in quiet mode. This means only output returned from the Bugzilla will be displayed; several more verbose log messages will not be displayed.

product = string

This is the default setting for the product field in bugs in this Bugzilla instance. It is possible to define this in the default section. However, it does not make sense to do so most of the time. If this is set, you will not be prompted for a product when you run bugz post, and this value will also be the default for bugz search.

component = string

This is the default setting for the component field in bugs in this Bugzilla instance. It is possible to define this in the default section. However, it does not make sense to do so most of the time. If this is set, you will not be prompted for a component when you run bugz post, and this will also be the default value for bugz search.

search_statuses = confirmed, in_progress, unconfirmed

This sets the default statuses to be used in a search command. It is a space separated list of Bugzilla statuses.

insecure = true | false

If this is set to true, pybugz will not validate the ssl certificate used during an https connection to this site. Do not use this setting unless you know exactly what you are doing.

## BUGS
The home page of this project is http://www.github.com/williamh/pybugz. Bugs should be reported to the bug tracker there.

## AUTHOR
William Hubbs <w.d.hubbs@gmail.com>


urlwatch-config

title: urlwatch-config(5)

summary: Configuration of urlwatch behavior

text:
# urlwatch-config(5)

## NAME
urlwatch-config - Configuration of urlwatch behavior

## SYNOPSIS
urlwatch --edit-config

## DESCRIPTION
The global configuration for urlwatch contains basic settings for the generic behavior of urlwatch as well as the Reporters.

## DISPLAY
In addition to always reporting changes (which is the whole point of urlwatch), urlwatch by default reports newly-added (new) pages and errors (error). You can change this behavior in the display section of the configuration:

```
display:

  new: true

  error: true

  unchanged: false

  empty-diff: true
```

If you set unchanged to true, urlwatch will always report all pages that are checked but have not changed.

The empty-diff settings control what happens if a page is changed, but due to e.g. a diff_filter the diff is reduced to the empty string. If set to true, urlwatch will report an (empty) change. If set to false, the change will not be included in the report.

### Filter changes are not applied for unchanged
Due to the way the filtered output is stored, unchanged will always report the old contents with the filters at the time of retrieval, meaning that any changes you do to the filter of a job will not be visible in the unchanged report. When the page changes, the new filter will be applied.

For this reason, unchanged cannot be used to test filters, you should use the --test-filter command line option to apply your current filter to the current page contents.

## REPORTERS
"Reporters" are the modules that deliver notifications through their respective medium when they are enabled through the configuration file.

See urlwatch-reporters(5) for reporter-specific options.

In addition to the reporter-specific options, all reporters support these options:

- enable: [bool] Activate the reporter. (default: False)

- separate: [bool] Send a report for each job rather than a combined report for all jobs. (default: False)

Reporters are implemented in a hierarchy, such that these common configuration settings will apply to all descendent reporters:

```
html
text
├───stdout
├───email
├───ifttt
├───webservice
│   ├───pushover
│   └───pushbullet
├───mailgun
├───telegram
├───slack
│   └───mattermost
├───discord
├───xmpp
├───prowl
└───shell
markdown
└───matrix
```

NOTE:

Setting the email reporter's html option to true will cause it to inherit from the html configuration.

Here is an example configuration that reports on standard output in color, as well as HTML e-mail using sendmail:

```
report:

  text:

    details: true

    footer: true

    line_length: 75

  html:

    diff: unified

    separate: true

  email:

    enabled: true

    method: sendmail

    sendmail:

        path: /usr/sbin/sendmail

    from: 'urlwatch@example.org'

    to: 'you@example.org'

    html: true

    subject: '{count} changes: {jobs}'

  stdout:

    color: true

    enabled: true
```

Any reporter-specific configuration must be below the report key in the configuration.

## JOB DEFAULTS
If you want to change some settings for all your jobs, edit the job_defaults section in your config file:

```
job_defaults:

  all:

    diff_tool: wdiff

  url:

    ignore_connection_errors: true
```

The above config file sets all jobs to use wdiff as diff tool, and all url jobs to ignore connection errors.

The possible sub-keys to job_defaults are:

- all: Applies to all your jobs, independent of its kind

- shell: Applies only to shell jobs (with key command)

- url: Applies only to url jobs (with key url)

- browser: Applies only to browser jobs (with key navigate)

See Jobs about the different job kinds and what the possible keys are.

## FILES
$XDG_CONFIG_HOME/urlwatch/urlwatch.yaml

## SEE ALSO
urlwatch(1), urlwatch-reporters(5), urlwatch-intro(7), urlwatch-cookbook(7)

## COPYRIGHT
2023 Thomas Perl