Skip to content

Commit

Permalink
Merge pull request #35 from RainbowHackerHorse/docs/add-manpage
Browse files Browse the repository at this point in the history 
Docs/add manpage
  • Loading branch information
@RainbowHackerHorse
RainbowHackerHorse authored Jun 8, 2018
2 parents 10e61aa + 82d0f89 commit b39d9a7
Show file tree
Hide file tree
Showing 8 changed files with 583 additions and 215 deletions.
2 changes: 1 addition & 1 deletion .circleci/config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ jobs:
command: sudo gem2.0 install fpm --no-ri --no-doc
- run:
name: BuildPkgDeb
command: sudo sh ~/vzvol_build/build/vzvol_build.sh 0.6.4 deb ~/vzvol_build [email protected]
command: sudo sh ~/vzvol_build/build/vzvol_build.sh 0.0.0 0 deb ~/vzvol_build [email protected]
- run:
name: InstallPkg
command: sudo dpkg -i ~/vzvol_build/vzvol_0.6.4_all.deb
Expand Down
9 changes: 5 additions & 4 deletions build/vzvol_build.sh
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#!/bin/sh
vzvol_build_version="${1}"
vzvol_build_type="${2}"
vzvol_git_location="${3}"
maintainer_email="${4}"
fpm -s dir -t "${vzvol_build_type}" -n vzvol -v "${vzvol_build_version}" -C "${vzvol_git_location}" --license=BSD-2-Clause -d pv -d dialog -d dosfstools -d xfsprogs -a noarch -m "${maintainer_email}" --vendor=@hacker_horse --description="A zfs zvol management tool" --url="https://github.com/RainbowHackerHorse/vzvol" --prefix=/usr/local bin/vzvol=bin/vzvol lib/linux/=lib/vzvol/lib/linux/ lib/shared/=lib/vzvol/lib/shared/ LICENSE=docs/LICENSE
vzvol_build_iteration="${2}"
vzvol_build_type="${3}"
vzvol_git_location="${4}"
maintainer_email="${5}"
fpm -s dir -t "${vzvol_build_type}" -n vzvol -v "${vzvol_build_version}" --iteration "${vzvol_build_iteration}" -C "${vzvol_git_location}" --license=BSD-2-Clause -d pv -d dialog -d dosfstools -d xfsprogs -a noarch -m "${maintainer_email}" --vendor=@hacker_horse --description="A zfs zvol management tool" --url="https://github.com/RainbowHackerHorse/vzvol" --prefix=/usr/local bin/vzvol=sbin/vzvol man/linux/vzvol.8=share/man/man8/vzvol.8 lib/linux/=lib/vzvol/lib/ lib/shared/=lib/vzvol/lib/ LICENSE=docs/LICENSE
143 changes: 36 additions & 107 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ fron ports.
- dosfstools
- xfsprogs
- pv
- zfsutils

## Contributing
Fork and open a PR with your changes.
Expand All @@ -41,110 +42,38 @@ to the bottom if it isn't already listed!

## Package Status
### vzvol is currently supported in the following OS pkg systems:
- FreeBSD Ports - `cd /usr/ports/sysutils/vzvol && make install clean`

### Unsupported but kept in mind during development
- Debian Linux - If you know a Debian pkg maintainer who would like to sponser us getting a pkg made, get us in touch!


## Help

```
vzvol is a shell script designed to help automate the process of
creating a ZFS zvol for use as a storage unit for virtualization, or testing.
vzvol was originally created to allow you to back a light .VMDK with a zvol for
use with VirtualBox, however additional functionality has been added over time to
make vzvol a general-use program. I hope you find it useful!
This script is released under the 2-clause BSD license.
(c) 2017, 2018 RainbowHackerHorse
https://github.com/RainbowHackerHorse/vzvol
-h | --help
Shows this help
zvol Creation Flags:
-s | --size
Allows you to set a size for the zvol.
Size should be set using M or G.
Example: --size 10G | -s 1024M
Defaults to 10G if nothing specified.
-u | --user
MANDATORY OPTION!!
Sets the user under which we grant permissions for the zvol.
No longer defaults to your username, and is a mandatory option.
-v | --volume
MANDATORY OPTION!!
Sets the zvol name. If nothing is specified or this option is left off,
the command will FAIL!
-p | --pool
This flag will allow you to override the logic to choose the zpool you want
your zvol on.
By default, this script selects the first zpool available, unless your
first pool is "bootpool" (as with an encrypted system).
If your first pool is "bootpool", this script will default to the second
listed pool, usually "zroot" in a default install.
-t | --type
This option allows you to set the disk type behavior.
The following types are accepted:
virtualbox - The default behavior, vzvol will create a shim VMDK to point to the created
zvol.
raw - Create a raw, normal zvol with no shim, in the default location of
/dev/zvol/poolname/volumename
--file-system
Setting this flag allows you to format the zvol with your choice of filesystem.
The default for vzvol is to not create a filesystem on the new zvol.
The following types are accepted:
Filesystems with support in FreeBSD:
zfs - Creates a zfs filesystem, using the name set in --volume as the pool name.
ufs - Create a FreeBSD compatible UFS2 filesystem.
fat32 - Create an MS-DOS compatible FAT32 filesystem.
Filesystems that require a port be installed:
*REQUIRES* sysutils/e2fsprogs!
ext2 - Creates a Linux-compatible ext2 filesystem.
ext3 - Creates a Linux-compatible ext3 filesystem.
ext4 - Creates a Linux-compatible ext4 filesystem.
*REQUIRES* sysutils/xfsprogs!
xfs - Create an XFS filesystem.
--import
The --import flag allows you to import the contents of a downloaded disk image to
your newly created zvol. This is useful when using a pre-installed VM image, such as
https://github.com/RainbowHackerHorse/FreeBSD-On-Linode
-p
The -p flag is used with --import to show a progress bar for image data importation
to the vzol. -p requires that sysutils/pv be installed.
zvol Management Flags:
--format
The --format flag allows you to reformat a zvol created by vzvol, using the same
options and arguments as --file-system.
You must specify the fs type, and then the zvol to format.
Example: vzvol --format xfs zroot/smartos
--delete
The --delete flag deletes the zvol you specify. If a .VMDK file is associated with
the zvol, the .VMDK will also be deleted.
You MUST specify the zpool the zvol resides on.
You can get this information from running vzvol --list or zfs list -t volume
Example: vzvol --delete zroot/smartos11
--list
List all zvols on your system, the type, any associated .VMDK files, how much space on disk
is used by the zvol, the maximum size of the zvol capacity, and the Filesystem, if
vzvol can determine it. Imported images will list FS as "imported", and any zvol that doesn't
have custom:FS set will report "unknown"
Example output:
ZVOL TYPE VMDK USED SIZE FS
zroot/smartos RAW none 20G 50G zfs
zroot/ubuntu1604 VirtualBox /home/username/VBoxDisks/ubuntu1604.vmdk 1.51G 10G ext4
```
#### FreeBSD Ports
1. `cd /usr/ports/sysutils/vzvol && make install clean` or `pkg install vzvol`

#### Debian (Using my repo)
1. Ensure `apt-transport-https` is installed.
2. Add `deb https://repo-hackerhorse-io.nyc3.digitaloceanspaces.com/deb/ debian main` to /etc/apt/sources.list.d/vzvol.list (Once DO allows for CNAMEs on Spaces, this will change to https://repo.hackerhorse.io/deb)
3. Run `sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys FF07F6AE`
4. Run `apt-get update`
5. Run `apt-get install vzvol`

### Unsupported
- Debian Linux - If you know a Debian pkg maintainer who would like to sponser us getting a pkg made officially, get us in touch!


## Building Linux Packages
I made building Linux packages easy here, thanks to FPM.

Dependencies: FPM

1. Clone the git repo
2. `cd` to where you cloned the repo to
3. `cd build`
4. ./vzvol_build.sh "version" "deb/rpm" "vzvol git directory" "maintainer email"

### Creating a repo
I'm lazy and found a thing called aptly. This is how I created the Debian repo.

1. `aptly repo create vzvol`
2. `aptly repo add vzvol vzvol_VERSION_all.deb`
3. `aptly snapshot create vzvol from repo vzvol`
4. `aptly publish -distribution=debian -architectures=amd64 snapshot vzvol`
5. `aptly publish -distribution=ubuntu -architectures=amd64 snapshot vzvol`

Your repo will be in ~/.aptly/public
Publish where you please, or just mirror mine!
105 changes: 2 additions & 103 deletions lib/shared/vzvol_showhelp.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,109 +2,8 @@
vzvol_showhelp() {
errorfunc='show_help'
cat << 'EOT'
vzvol is a shell script designed to help automate the process of
creating a ZFS zvol for use as a storage unit for virtualization, or testing.
vzvol was originally created to allow you to back a light .VMDK with a zvol for
use with VirtualBox, however additional functionality has been added over time
to make vzvol a general-use program. I hope you find it useful!
This script is released under the 2-clause BSD license.
(c) 2017 RainbowHackerHorse
https://github.com/RainbowHackerHorse/vzvol
-h | --help
Shows this help
zvol Creation Flags:
-s | --size
Allows you to set a size for the zvol.
Size should be set using M or G.
Example: --size 10G | -s 1024M
Defaults to 10G if nothing specified.
-u | --user
MANDATORY OPTION!!
Sets the user under which we grant permissions for the zvol.
No longer defaults to your username, and is a mandatory option.
-v | --volume
MANDATORY OPTION!!
Sets the zvol name. If nothing is specified or this option is left off,
the command will FAIL!
-p | --pool
This flag will allow you to override the logic to choose the zpool you want
your zvol on.
By default, this script selects the first zpool available, unless your
first pool is "bootpool" (as with an encrypted system).
If your first pool is "bootpool", this script will default to the second
listed pool, usually "zroot" in a default install.
-t | --type
This option allows you to set the disk type behavior.
The following types are accepted:
-t virtualbox
- The default behavior, vzvol will create a shim VMDK to point to
the created zvol.
-t raw
- Create a raw, normal zvol with no shim, in the default location of
/dev/zvol/poolname/volumename
--file-system
Setting this flag allows you to format the zvol with your choice of filesystem.
The default for vzvol is to not create a filesystem on the new zvol.
The following types are accepted:
Filesystems with support in FreeBSD:
zfs - Creates a zfs filesystem, using the name set in --volume
ufs - Create a FreeBSD compatible UFS2 filesystem.
fat32 - Create an MS-DOS compatible FAT32 filesystem.
Filesystems that require a port be installed:
*REQUIRES* sysutils/e2fsprogs!
ext2 - Creates a Linux-compatible ext2 filesystem.
ext3 - Creates a Linux-compatible ext3 filesystem.
ext4 - Creates a Linux-compatible ext4 filesystem.
*REQUIRES* sysutils/xfsprogs!
xfs - Create an XFS filesystem.
--import
The --import flag allows you to import the contents of a downloaded disk image
to your newly created zvol. This is useful when using a pre-installed VM image,
such as https://github.com/RainbowHackerHorse/FreeBSD-On-Linode
-p
The -p flag is used with --import to show a progress bar for image data
importation to the vzol. -p requires that sysutils/pv be installed.
On Linux, this option requires you to have dialog installed.
zvol Management Flags:
--format
The --format flag allows you to reformat a zvol created by vzvol, using the same
options and arguments as --file-system.
You must specify the fs type, and then the zvol to format.
Example: vzvol --format xfs zroot/smartos
--delete
The --delete flag deletes the zvol you specify. If a .VMDK file is associated
with the zvol, the .VMDK will also be deleted.
You MUST specify the zpool the zvol resides on.
You can get this information from running vzvol --list or zfs list -t volume
Example: vzvol --delete zroot/smartos11
--list
List all zvols on your system, the type, any associated .VMDK files, how much
space on disk is used by the zvol, the maximum size of the zvol capacity, and
the Filesystem, if vzvol can determine it. Imported images will list FS as
"imported", and any zvol that does not have custom:fs set will report "unknown".
Example output:
ZVOL TYPE VMDK USED SIZE FS
zroot/smartos RAW none 20G 50G zfs
zroot/ubuntu VirtualBox /home/u/VBoxDisks/ubuntu.vmdk 1.51G 10G ext4
see "man 8 vzvol"
This --help function is deprecated and will be removed in a future release.
EOT
}
Loading

0 comments on commit b39d9a7

Please sign in to comment.