sedpoquj

sedpoquj is an application for managing KVM-QEMU virtual machines via virsh.

Use-cases

• Automate interactions with virtual machines
• Automate basic interactions with encrypted virtual machines
• Pass information into virtual machine from host machine using only hypervisor (via typing string into virtual machine)
• Automate command execution on virtual machines using only hypervisor
• Automating interactions with virtual machine images

Advanced use-cases

• Pass credentials to login forms of online services in virtual machines
• Automate start of encrypted virtual machine via macro using encryption key and user password from virtual machine credentials
• Ease process of recreating encrypted virtual machine using ability to copy credentials

Features

General

• Type custom string into virtual machine
• List available virtual machines
• Enable or disable virtual machine autostart feature
• Open GUI console of virtual machine
• Mount/unmount virtual machine images (img/qcow) with support of encrypted partition via LUKS
• Perform more complicated interactions with virtual machine using macros, which are defined via JSON.
• Show IP address of a virtual machine
• Change virtual machine state

Credentials

• List existing credentials of virtual machines
• Add new virtual machine credentials
• Type credential value in virtual machine
• Remove credentials from virtual machine credentials
• Copy credentials from one virtual machine credentials to another virtual machine credentials

By default, machine credentials will be stored in encrypted file creds.json.enc using IETF XChaCha20Poly1305 encryption.

By default, encryption parameters stored in file encryption_params.

Installation

git clone https://gitlab.com/mongalless/sedpoquj
cd sedpoquj
shards build
./bin/sedpoquj -h

Might require installation of libsodium. (https://github.com/didactic-drunk/sodium.cr#installation)

Miscellaneous

Review script files in scripts directory and run:

cp ./.env.example .env
./scripts/init.sh
./scripts/auto_complete.sh
source /etc/bash_completion.d/sedpoquj

Setting SEDPOQUJ_PATH env variable via running init.sh is required for application, auto_complete.sh is optional.

Note about auto-complete: for any command it will show full list of options. Use -h to see the precise list of options for command.

Usage

• Type string into virtual machine: sedpoquj --machine_name machine_name --string "some string"
• Add virtual machine credentials key-value: sedpoquj credentials add --machine_name machine_name --credential_key test_key --credential_value test_value
• Check virtual machine autostart status: sedpoquj features autostart show_status --machine_name machine
• Mount iso partition: sedpoquj image mount_plain --image_path image_path --mount_path mount_path
• Show virtual machine IP address: sedpoquj network show_ip --machine_name machine_name
• Execute start command for virtual machine: sedpoquj vm_command start --machine_name machine_name
• Use start_machine macro to launch virtual machine: sedpoquj macros --selected_macro_command start_machine --machine_name machine_name --luks_key luks_key --user_password_key user_password_key

Check out examples directory for more usage examples.

General option value formatting requires surrounding value with " symbol if value contains spaces. Example: --string "string with spaces".

Development

Install git hooks

Make sure that you have lefthook installed on your system.

Installation guide: https://github.com/evilmartians/lefthook/blob/master/docs/install.md

lefthook install

Build

shards install
shards build

Docs

Run crystal docs to generate documentation.

Format of branches:

[name_of_project-number_of_issue]

• sedpoquj-1

Format of commits:

[short description]

• Setup RAT on filesystem after sudo command execution

Format of PR-s:

[branch_name: description of task]

• sedpoquj-1: If executed command starts with sudo, use escalated permissions to persist on system using RAT

Contributing

1. Fork it (https://gitlab.com/mongalless/sedpoquj/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

WTFPLv2.

Contributors

• mongalless - creator and maintainer