diff --git a/examples/preseeds/ubuntu_preseed.cfg b/examples/preseeds/ubuntu_preseed.cfg new file mode 100644 index 000000000..1786445fd --- /dev/null +++ b/examples/preseeds/ubuntu_preseed.cfg @@ -0,0 +1,61 @@ +# Preseeding only locale sets language, country and locale. +d-i debian-installer/locale string en_US + +# Keyboard selection. +d-i console-setup/ask_detect boolean false +d-i keyboard-configuration/xkb-keymap select us + +choose-mirror-bin mirror/http/proxy string + +### Clock and time zone setup +d-i clock-setup/utc boolean true +d-i time/zone string UTC + +# Avoid that last message about the install being complete. +d-i finish-install/reboot_in_progress note + +# This is fairly safe to set, it makes grub install automatically to the MBR +# if no other operating system is detected on the machine. +d-i grub-installer/only_debian boolean true + +# This one makes grub-installer install to the MBR if it also finds some other +# OS, which is less safe as it might not be able to boot that other OS. +d-i grub-installer/with_other_os boolean true + +### Mirror settings +# If you select ftp, the mirror/country string does not need to be set. +d-i mirror/country string manual +d-i mirror/http/directory string /ubuntu/ +d-i mirror/http/hostname string archive.ubuntu.com +d-i mirror/http/proxy string + +### Partitioning +d-i partman-auto/method string lvm + +# This makes partman automatically partition without confirmation. +d-i partman-md/confirm boolean true +d-i partman-partitioning/confirm_write_new_label boolean true +d-i partman/choose_partition select finish +d-i partman/confirm boolean true +d-i partman/confirm_nooverwrite boolean true + +### Account setup +d-i passwd/user-fullname string vagrant +d-i passwd/user-uid string 1000 +d-i passwd/user-password password vagrant +d-i passwd/user-password-again password vagrant +d-i passwd/username string vagrant + +# The installer will warn about weak passwords. If you are sure you know +# what you're doing and want to override it, uncomment this. +d-i user-setup/allow-password-weak boolean true +d-i user-setup/encrypt-home boolean false + +### Package selection +tasksel tasksel/first standard +d-i pkgsel/include string openssh-server build-essential +d-i pkgsel/install-language-support boolean false + +# disable automatic package updates +d-i pkgsel/update-policy select none +d-i pkgsel/upgrade select full-upgrade \ No newline at end of file diff --git a/website/source/docs/communicators/index.html.md b/website/source/docs/communicators/index.html.md new file mode 100644 index 000000000..802d79fdf --- /dev/null +++ b/website/source/docs/communicators/index.html.md @@ -0,0 +1,32 @@ +--- +description: | + Communicators are the mechanism Packer uses to upload files, execute + scripts, etc. with the machine being created. +layout: docs +page_title: Communicators +sidebar_current: 'docs-communicators' +--- + +# Communicators + +Communicators are the mechanism Packer uses to upload files, execute scripts, +etc. with the machine being created. + +Communicators are configured within the +[builder](/docs/templates/builders.html) section. Packer currently supports +three kinds of communicators: + +- `none` - No communicator will be used. If this is set, most provisioners + also can't be used. + +- [ssh](/docs/communicators/ssh.html) - An SSH connection will be established to the machine. This is + usually the default. + +- [winrm](/docs/communicators/winrm.html) - A WinRM connection will be established. + +In addition to the above, some builders have custom communicators they can use. +For example, the Docker builder has a "docker" communicator that uses +`docker exec` and `docker cp` to execute scripts and copy files. + +For more details on how to use each communicator, click the links above to be +taken to each communicator's page. \ No newline at end of file diff --git a/website/source/docs/templates/communicator.html.md b/website/source/docs/communicators/ssh.html.md similarity index 60% rename from website/source/docs/templates/communicator.html.md rename to website/source/docs/communicators/ssh.html.md index de5c91c43..2065d2dd4 100644 --- a/website/source/docs/templates/communicator.html.md +++ b/website/source/docs/communicators/ssh.html.md @@ -1,41 +1,60 @@ --- description: | - Communicators are the mechanism Packer uses to upload files, execute scripts, - etc. with the machine being created. + The SSH communicator uses SSH to upload files, execute scripts, etc. on + the machine being created. layout: docs -page_title: 'Communicators - Templates' -sidebar_current: 'docs-templates-communicators' +page_title: 'Communicators - SSH' +sidebar_current: 'docs-communicators-ssh' --- -# Template Communicators +# SSH Communicator Communicators are the mechanism Packer uses to upload files, execute scripts, -etc. with the machine being created. - -Communicators are configured within the -[builder](/docs/templates/builders.html) section. Packer currently supports -three kinds of communicators: - -- `none` - No communicator will be used. If this is set, most provisioners - also can't be used. - -- `ssh` - An SSH connection will be established to the machine. This is - usually the default. - -- `winrm` - A WinRM connection will be established. - -In addition to the above, some builders have custom communicators they can use. -For example, the Docker builder has a "docker" communicator that uses -`docker exec` and `docker cp` to execute scripts and copy files. - -## Using a Communicator - -By default, the SSH communicator is usually used. Additional configuration may -not even be necessary, since some builders such as Amazon automatically -configure everything. - -However, to specify a communicator, you set the `communicator` key within a -build. Multiple builds can have different communicators. Example: +etc. on the machine being created, and ar configured within the +[builder](/docs/templates/builders.html) section. + +The SSH communicator does this by using the SSH protocol. It is the default +communicator for a majority of builders. + +If you have an SSH agent configured on the host running Packer, and SSH agent +authentication is enabled in the communicator config, Packer will automatically +forward the SSH agent to the remote host. + +## Getting Ready to Use the SSH Communicator + +The SSH communicator is the default communicator for a majority of builders, but +depending on your builder it may not work "out of the box". + +If you are building from a cloud image (for example, building on Amazon), there +is a good chance that your cloud provider has already preconfigured SSH on the +image for you, meaning that all you have to do is configure the communicator in +the Packer template. + +However, if you are building from a brand-new and unconfigured operating system +image, you will almost always have to perform some extra work to configure SSH +on the guest machine. For most operating system distributions, this work will +be performed by a +(boot command)[/docs/builders/vmware-iso.html#boot-configuration] +that references a file which provides answers to the normally-interactive +questions you get asked when installing an operating system. The name of this +file varies by operating system; some common examples are the "preseed" file +required by Debian, the "kickstart" file required by CentOS or the +"answer file", also known as the Autounattend.xml file, required by Windows. +For simplicity's sake, we'll refer to this file as the "preseed" file in the +rest of the documentation. + +If you are unfamiliar with how to use a preseed file for automatic +bootstrapping of an image, please either take a look at our [quick guides](/guides/automatic-operating-system-installs/index.html) to +image bootstrapping, or research automatic configuration for your specific +guest operating system. Knowing how to automatically initalize your operating +system is critical for being able to successfully use Packer. + +## Using The SSH Communicator + +To specify a communicator, you set the `communicator` key within a +build. If your template contains multiple builds, you can have a different +communicator configured for each. Here's an extremely basic example of +configuring the SSH communicator for an Amazon builder: ``` json { @@ -48,10 +67,10 @@ build. Multiple builds can have different communicators. Example: } ``` -After specifying the `communicator`, you can specify a number of other +After specifying the `communicator` type, you can specify a number of other configuration parameters for that communicator. These are documented below. -## SSH Communicator +## SSH Communicator Options The SSH communicator connects to the host via SSH. If you have an SSH agent configured on the host running Packer, and SSH agent authentication is enabled @@ -176,58 +195,4 @@ And the following MACs: - hmac-sha2-256 - `hmac-sha2-256-etm@openssh.com` -## WinRM Communicator - -The WinRM communicator has the following options. - -- `winrm_host` (string) - The address for WinRM to connect to. - - NOTE: If using an Amazon EBS builder, you can specify the interface WinRM - connects to via - [`ssh_interface`](https://www.packer.io/docs/builders/amazon-ebs.html#ssh_interface) - -- `winrm_insecure` (boolean) - If `true`, do not check server certificate - chain and host name. - -- `winrm_password` (string) - The password to use to connect to WinRM. - -- `winrm_port` (number) - The WinRM port to connect to. This defaults to - `5985` for plain unencrypted connection and `5986` for SSL when - `winrm_use_ssl` is set to true. - -- `winrm_timeout` (string) - The amount of time to wait for WinRM to become - available. This defaults to `30m` since setting up a Windows machine - generally takes a long time. - -- `winrm_use_ntlm` (boolean) - If `true`, NTLMv2 authentication (with session - security) will be used for WinRM, rather than default (basic - authentication), removing the requirement for basic authentication to be - enabled within the target guest. Further reading for remote connection - authentication can be found - [here](https://msdn.microsoft.com/en-us/library/aa384295(v=vs.85).aspx). - -- `winrm_use_ssl` (boolean) - If `true`, use HTTPS for WinRM. - -- `winrm_username` (string) - The username to use to connect to WinRM. - -## Pausing Before Connecting -We recommend that you enable SSH or WinRM as the very last step in your -guest's bootstrap script, but sometimes you may have a race condition where -you need Packer to wait before attempting to connect to your guest. - -If you end up in this situation, you can use the template option -`pause_before_connecting`. By default, there is no pause. For example: - -``` -{ - "communicator": "ssh", - "ssh_username": "myuser", - "pause_before_connecting": "10m" -} -``` - -In this example, Packer will check whether it can connect, as normal. But once -a connection attempt is successful, it will disconnect and then wait 10 minutes -before connecting to the guest and beginning provisioning. - diff --git a/website/source/docs/communicators/ssh.html.md.erb b/website/source/docs/communicators/ssh.html.md.erb new file mode 100644 index 000000000..988870816 --- /dev/null +++ b/website/source/docs/communicators/ssh.html.md.erb @@ -0,0 +1,87 @@ +--- +description: | + The SSH communicator uses SSH to upload files, execute scripts, etc. on + the machine being created. +layout: docs +page_title: 'Communicators - SSH' +sidebar_current: 'docs-communicators-ssh' +--- + +# SSH Communicator + +Communicators are the mechanism Packer uses to upload files, execute scripts, +etc. on the machine being created, and ar configured within the +[builder](/docs/templates/builders.html) section. + +The SSH communicator does this by using the SSH protocol. It is the default +communicator for a majority of builders. + +If you have an SSH agent configured on the host running Packer, and SSH agent +authentication is enabled in the communicator config, Packer will automatically +forward the SSH agent to the remote host. + +## Getting Ready to Use the SSH Communicator + +The SSH communicator is the default communicator for a majority of builders, but +depending on your builder it may not work "out of the box". + +If you are building from a cloud image (for example, building on Amazon), there +is a good chance that your cloud provider has already preconfigured SSH on the +image for you, meaning that all you have to do is configure the communicator in +the Packer template. + +However, if you are building from a brand-new and unconfigured operating system +image, you will almost always have to perform some extra work to configure SSH +on the guest machine. For most operating system distributions, this work will +be performed by a [boot command](/docs/builders/vmware-iso.html#boot-configuration) +that references a file which provides answers to the normally-interactive +questions you get asked when installing an operating system. The name of this +file varies by operating system; some common examples are the "preseed" file +required by Debian, the "kickstart" file required by CentOS or the +"answer file", also known as the Autounattend.xml file, required by Windows. +For simplicity's sake, we'll refer to this file as the "preseed" file in the +rest of the documentation. + +If you are unfamiliar with how to use a preseed file for automatic +bootstrapping of an image, please either take a look at our +[quick guides](/guides/automatic-operating-system-installs/index.html) to +image bootstrapping, or research automatic configuration for your specific +guest operating system. Knowing how to automatically initalize your operating +system is critical for being able to successfully use Packer. + +## SSH Communicator + +The SSH communicator connects to the host via SSH. If you have an SSH agent +configured on the host running Packer, and SSH agent authentication is enabled +in the communicator config, Packer will automatically forward the SSH agent to +the remote host. + +The SSH communicator has the following options: + +<%= partial "partials/helper/communicator/SSH-not-required" %> + +### SSH Communicator Details + +Packer will only use one authentication method, either `publickey` or if +`ssh_password` is used packer will offer `password` and `keyboard-interactive` +both sending the password. In other words Packer will not work with *sshd* +configured with more than one configured authentication method using +`AuthenticationMethods`. + +Packer supports the following ciphers: + +- aes128-ctr +- aes192-ctr +- aes256-ctr +- arcfour128 +- arcfour256 +- arcfour +- `es128-gcm@openssh.com` +- `acha20-poly1305@openssh.com` + +And the following MACs: + +- hmac-sha1 +- hmac-sha1-96 +- hmac-sha2-256 +- `hmac-sha2-256-etm@openssh.com` \ No newline at end of file diff --git a/website/source/docs/communicators/winrm.html.md b/website/source/docs/communicators/winrm.html.md new file mode 100644 index 000000000..6918b4115 --- /dev/null +++ b/website/source/docs/communicators/winrm.html.md @@ -0,0 +1,160 @@ +--- +description: | + Communicators are the mechanism Packer uses to upload files, execute scripts, + etc. with the machine being created. +layout: docs +page_title: 'Communicators - Templates' +sidebar_current: 'docs-templates-communicators' +--- + +# Template Communicators + +Communicators are the mechanism Packer uses to upload files, execute scripts, +etc. with the machine being created. + +Communicators are configured within the +[builder](/docs/templates/builders.html) section. Packer currently supports +three kinds of communicators: + +- `none` - No communicator will be used. If this is set, most provisioners + also can't be used. + +- `ssh` - An SSH connection will be established to the machine. This is + usually the default. + +- `winrm` - A WinRM connection will be established. + +In addition to the above, some builders have custom communicators they can use. +For example, the Docker builder has a "docker" communicator that uses +`docker exec` and `docker cp` to execute scripts and copy files. + +## Using a Communicator + +By default, the SSH communicator is usually used. Additional configuration may +not even be necessary, since some builders such as Amazon automatically +configure everything. + +However, to specify a communicator, you set the `communicator` key within a +build. Multiple builds can have different communicators. Example: + +``` json +{ + "builders": [ + { + "type": "amazon-ebs", + "communicator": "ssh" + } + ] +} +``` + +After specifying the `communicator`, you can specify a number of other +configuration parameters for that communicator. These are documented below. + +## WinRM Communicator + +The WinRM communicator has the following options. + +- `winrm_host` (string) - The address for WinRM to connect to. + + NOTE: If using an Amazon EBS builder, you can specify the interface WinRM + connects to via + [`ssh_interface`](https://www.packer.io/docs/builders/amazon-ebs.html#ssh_interface) + +- `winrm_insecure` (boolean) - If `true`, do not check server certificate + chain and host name. + +- `winrm_password` (string) - The password to use to connect to WinRM. + +- `winrm_port` (number) - The WinRM port to connect to. This defaults to + `5985` for plain unencrypted connection and `5986` for SSL when + `winrm_use_ssl` is set to true. + +- `winrm_timeout` (string) - The amount of time to wait for WinRM to become + available. This defaults to `30m` since setting up a Windows machine + generally takes a long time. + +- `winrm_use_ntlm` (boolean) - If `true`, NTLMv2 authentication (with session + security) will be used for WinRM, rather than default (basic + authentication), removing the requirement for basic authentication to be + enabled within the target guest. Further reading for remote connection + authentication can be found + [here](https://msdn.microsoft.com/en-us/library/aa384295(v=vs.85).aspx). + +- `winrm_use_ssl` (boolean) - If `true`, use HTTPS for WinRM. + +- `winrm_username` (string) - The username to use to connect to WinRM. + +## Pausing Before Connecting +We recommend that you enable SSH or WinRM as the very last step in your +guest's bootstrap script, but sometimes you may have a race condition where +you need Packer to wait before attempting to connect to your guest. + +If you end up in this situation, you can use the template option +`pause_before_connecting`. By default, there is no pause. For example: + +``` +{ + "communicator": "ssh", + "ssh_username": "myuser", + "pause_before_connecting": "10m" +} +``` + +In this example, Packer will check whether it can connect, as normal. But once +a connection attempt is successful, it will disconnect and then wait 10 minutes +before connecting to the guest and beginning provisioning. + + +## Configuring WinRM as part of an Autounattend File + +You can add a batch file to your autounattend that contains the commands for +configuring winrm. Depending on your winrm setup, this could be a complex batch +file, or a very simple one. + +``` xml + + ... + + cmd.exe /c a:\winrmConfig.bat + Configure WinRM + 3 + true + + ... + +``` + +The winrmConfig.bat referenced above can be as simple as + +``` +rem basic config for winrm +cmd.exe /c winrm quickconfig -q + +rem allow unencrypted traffic, and configure auth to use basic username/password auth +cmd.exe /c winrm set winrm/config/service @{AllowUnencrypted="true"} +cmd.exe /c winrm set winrm/config/service/auth @{Basic="true"} + +rem update firewall rules to open the right port and to allow remote administration +cmd.exe /c netsh advfirewall firewall set rule group="remote administration" new enable=yes + +rem restart winrm +cmd.exe /c net stop winrm +cmd.exe /c net start winrm +``` + +This batch file will only work for http connections, not https, but will enable +you to connect using only the username and password created earlier in the +Autounattend file. The above batchfile will allow you to connect using a very +simple Packer config: + +```json + ... + "communicator": "winrm", + "winrm_username": "packeruser", + "winrm_password": "SecretPassword" + ... +``` + +If you want to set winRM up for https, things will be a bit more complicated. +We'll explore \ No newline at end of file diff --git a/website/source/docs/communicators/winrm.html.md.erb b/website/source/docs/communicators/winrm.html.md.erb new file mode 100644 index 000000000..af32caedd --- /dev/null +++ b/website/source/docs/communicators/winrm.html.md.erb @@ -0,0 +1,198 @@ +--- +description: | + Communicators are the mechanism Packer uses to upload files, execute scripts, + etc. with the machine being created. +layout: docs +page_title: 'Communicators - Templates' +sidebar_current: 'docs-communicators-winrm' +--- + +# WinRM Communicator + +Communicators are the mechanism Packer uses to upload files, execute scripts, +etc. with the machine being created. The WinRM communicator uses the +Windows Remote Management protocol to do this. + +## Getting Ready to Use the WinRM Communicator + +The WinRM communicator is not the default communicator, so you will always have +to set the `"communicator": "winrm",` template option explicitly. In addition, +you will almost always have to provide a pre-run script that enables and +configures WinRM on the guest machine. This will generally be in the form of a +powershell script or a batch file. + +If you are building from a brand-new and unconfigured operating system +image, you will need to provide this pre-run script as part of your +Autounattend.xml file, required by Windows for automatic operating system +installation. If you are building in a cloud or from a pre-installed image, your +method for providing this pre-run script will vary based on the builder. Please +refer to each builder's documentation for more information on how to supply the +winrm configuration script. + +If you are unfamiliar with how to use an autounattend file, take a look at our +[quick guides](/guides/automatic-operating-system-installs/index.html); knowing +how to automatically initalize your operating system is critical for being able +to successfully use Packer to build from an iso. + +## WinRM Communicator Options + +<%= partial "partials/helper/communicator/WinRM-not-required" %> + +## Examples + +### Basics of WinRM Connection + +Please note that WinRM is not a Packer-specific protocol. Microsoft has a great +deal of documentation about WinRM. If you find after reading this guide that +you are still not able to connect via WinRM, check the +[Microsoft documentation](https://docs.microsoft.com/en-us/windows/win32/winrm/installation-and-configuration-for-windows-remote-management) +to make sure there isn't anything you're missing. + +There are some steps that you will normally need to take in order for Packer +to be able to connect via WinRM + +1. Set up a username and password that Packer to connect with. +2. Make any necesary registry edits to enable remote execution + (and remote execution with elevated privileges, if needed) +3. Start WinRM, setting any config needed for allowing basic auth +4. Open ports 5985 and/or 5986 depending on how you're connecting +5. launch WinRM and set it to automatically launch when the computer restarts +6. If necessary, generate a self-signed certificate or provide a real certificate + to the WinRM listener. + +#### Configuring WinRM in VMWare + +If you are configuring WinRM using an Autounattend.xml, the simplest way to set +up WinRM is to put the configuration commands directly into the Autounattend +file as shown [here](https://github.com/StefanScherer/packer-windows/blob/6e603e904e9b280eeb97f7eb542940a043954112/answer_files/2008_r2_core/Autounattend.xml#L157-L234) + +Instead of entering each line individually, you can also add a batch file to +your autounattend that contains the commands for configuring winrm. Depending +on your winrm setup, this could be a complex batch file, or a very simple one. + +Below is an example of how we would call a batch file from inside the +Autounattend file. + +``` xml + + ... + + cmd.exe /c a:\winrmConfig.bat + Configure WinRM + 3 + true + + ... + +``` +It is also possible to call powershell scripts in a similar manner. + +The winrmConfig.bat referenced above can be as simple as + +``` +rem basic config for winrm +cmd.exe /c winrm quickconfig -q + +rem allow unencrypted traffic, and configure auth to use basic username/password auth +cmd.exe /c winrm set winrm/config/service @{AllowUnencrypted="true"} +cmd.exe /c winrm set winrm/config/service/auth @{Basic="true"} + +rem update firewall rules to open the right port and to allow remote administration +cmd.exe /c netsh advfirewall firewall set rule group="remote administration" new enable=yes + +rem restart winrm +cmd.exe /c net stop winrm +cmd.exe /c net start winrm +``` + +Please note that the above batch file is _extremely_ simplistic, and not secure. +It is intended to be an example of the bare minimum configuration. Below, you'll +find a more complicated example of a more secure WinRM configuration process. + +This batch file will only work for http connections, not https, but will enable +you to connect using only the username and password created earlier in the +Autounattend file. The above batchfile will allow you to connect using a very +simple Packer config: + +```json + "communicator": "winrm", + "winrm_username": "packeruser", + "winrm_password": "SecretPassword" +``` + +A more complex example of a powershell script used for configuration can be seen +below. + +```powershell +# A Packer config that works with this example would be: +# +# +# "winrm_username": "Administrator", +# "winrm_password": "SuperS3cr3t!!!", +# "winrm_insecure": true, +# "winrm_use_ssl": true +# +# + +# Create username and password +net user Administrator SuperS3cr3t!!! +wmic useraccount where "name='Administrator'" set PasswordExpires=FALSE + +Set-ExecutionPolicy Unrestricted -Scope LocalMachine -Force -ErrorAction Ignore + +# Don't set this before Set-ExecutionPolicy as it throws an error +$ErrorActionPreference = "stop" + +# Remove HTTP listener +Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse + +# Create a self-signed certificate to let ssl work +$Cert = New-SelfSignedCertificate -CertstoreLocation Cert:\LocalMachine\My -DnsName "packer" +New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address * -CertificateThumbPrint $Cert.Thumbprint -Force + +# WinRM +write-output "Setting up WinRM" +write-host "(host) setting up WinRM" + +# Configure WinRM to allow unencrypted communication, and provide the +# self-signed cert to the WinRM listener. +cmd.exe /c winrm quickconfig -q +cmd.exe /c winrm set "winrm/config/service" '@{AllowUnencrypted="true"}' +cmd.exe /c winrm set "winrm/config/client" '@{AllowUnencrypted="true"}' +cmd.exe /c winrm set "winrm/config/service/auth" '@{Basic="true"}' +cmd.exe /c winrm set "winrm/config/client/auth" '@{Basic="true"}' +cmd.exe /c winrm set "winrm/config/service/auth" '@{CredSSP="true"}' +cmd.exe /c winrm set "winrm/config/listener?Address=*+Transport=HTTPS" "@{Port=`"5986`";Hostname=`"packer`";CertificateThumbprint=`"$($Cert.Thumbprint)`"}" + +# Make sure appropriate firewall port openings exist +cmd.exe /c netsh advfirewall firewall set rule group="remote administration" new enable=yes +cmd.exe /c netsh firewall add portopening TCP 5986 "Port 5986" + +# Restart WinRM, and set it so that it auto-launches on startup. +cmd.exe /c net stop winrm +cmd.exe /c sc config winrm start= auto +cmd.exe /c net start winrm +``` + +Please note that having WinRM auto-launch on all start ups may not be the right +choice for you, if you don't need the server to recieve WinRM connections in the +future. Clean up after yourself and close unnecesary firewall ports at a final +provisioning step to make sure your image is secure. + +#### Configuring WinRM in the Cloud + +Most clouds allow you to provide a configuration script that runs when the +instance is launched. In AWS, this is the +[user_data_file](/docs/builders/amazon-ebs.html#user_data_file). In Google +Cloud, this is provided using the `windows-startup-script-cmd` +[metadata](/docs/builders/googlecompute.html#metadata) tag. +[Example](/docs/builders/googlecompute.html#windows-example) + +Essentially, these files are powershell or cmd scripts that configure winrm, +without having to be wrapped in an Autounattend. Provide the script in the +format requested by each cloud, and make sure you manually configure any +firewall rules that the cloud doesn't allow you to manage internally. More +specific details for each cloud can be found in the builder sections. + +The above examples will work in cloud prep too, but may be overkill depending on +how much preconfiguration the cloud has done for you. \ No newline at end of file diff --git a/website/source/docs/templates/communicator.html.md.erb b/website/source/docs/templates/communicator.html.md.erb index 6d801e467..8e7fefc40 100644 --- a/website/source/docs/templates/communicator.html.md.erb +++ b/website/source/docs/templates/communicator.html.md.erb @@ -13,73 +13,40 @@ Communicators are the mechanism Packer uses to upload files, execute scripts, etc. with the machine being created. Communicators are configured within the -[builder](/docs/templates/builders.html) section. +[builder](/docs/templates/builders.html) section. All communicators have the following options: <%= partial "partials/helper/communicator/Config-not-required" %> -## Using a Communicator - -By default, the SSH communicator is usually used. Additional configuration may -not even be necessary, since some builders such as Amazon automatically -configure everything. - -However, to specify a communicator, you set the `communicator` key within a -build. Multiple builds can have different communicators. Example: - -``` json -{ - "builders": [ - { - "type": "amazon-ebs", - "communicator": "ssh" - } - ] -} -``` - -After specifying the `communicator`, you can specify a number of other -configuration parameters for that communicator. These are documented below. - - -## SSH Communicator - -The SSH communicator connects to the host via SSH. If you have an SSH agent -configured on the host running Packer, and SSH agent authentication is enabled -in the communicator config, Packer will automatically forward the SSH agent to -the remote host. - -The SSH communicator has the following options: - -<%= partial "partials/helper/communicator/SSH-not-required" %> - -### SSH Communicator Details - -Packer will only use one authentication method, either `publickey` or if -`ssh_password` is used packer will offer `password` and `keyboard-interactive` -both sending the password. In other words Packer will not work with *sshd* -configured with more than one configured authentication method using -`AuthenticationMethods`. - -Packer supports the following ciphers: - -- aes128-ctr -- aes192-ctr -- aes256-ctr -- arcfour128 -- arcfour256 -- arcfour -- `es128-gcm@openssh.com` -- `acha20-poly1305@openssh.com` - -And the following MACs: - -- hmac-sha1 -- hmac-sha1-96 -- hmac-sha2-256 -- `hmac-sha2-256-etm@openssh.com` - -## WinRM Communicator - -<%= partial "partials/helper/communicator/WinRM-not-required" %> +## Getting Ready to Use the Communicator + +Depending on your builder, your communicator may not have all it needs in order +to work "out of the box". + +If you are building from a cloud image (for example, building on Amazon), there +is a good chance that your cloud provider has already preconfigured SSH on the +image for you, meaning that all you have to do is configure the communicator in +the Packer template. + +However, if you are building from a brand-new and unconfigured operating system +image, you will almost always have to perform some extra work to configure SSH +on the guest machine. For most operating system distributions, this work will +be performed by a [boot_command](/docs/builders/vmware-iso.html#boot-command) that references a file which +provides answers to the normally-interactive questions you get asked when +installing an operating system. The name of this file varies by operating +system; some common examples are the "preseed" file required by Debian, the +"kickstart" file required by CentOS or the "answer file", also known as the +Autounattend.xml file, required by Windows. For simplicity's sake, we'll refer +to this file as the "preseed" file in the rest of the documentation. + +If you are unfamiliar with how to use a preseed file for automatic +bootstrapping of an image, please either take a look at our quick guides to +image bootstrapping, or research automatic configuration for your specific +guest operating system. Knowing how to automatically initalize your operating +system is critical for being able to successfully use Packer. + +## Communicator-Specific Options + +For more details on how to use each communicator, visit the +[communicators](/docs/communicators/index.html) page. \ No newline at end of file diff --git a/website/source/guides/automatic-operating-system-installs/autounattend_windows.html.md b/website/source/guides/automatic-operating-system-installs/autounattend_windows.html.md new file mode 100644 index 000000000..0f6404ff8 --- /dev/null +++ b/website/source/guides/automatic-operating-system-installs/autounattend_windows.html.md @@ -0,0 +1,97 @@ +--- +layout: guides +sidebar_current: automatic-operating-system-installs-unattended-installation-windows +page_title: Unattended Windows Installation +description: |- + Learn how to use an autounattend file to automatically answer installation + questions and enable Packer to connect to your windows instnace. +--- + +# Unattended Installation for Windows + +Unattended Windows installation is done via "Answer Files", or "Unattend files". + +These files are generally named "autounattend.xml". They are not +Packer-specific tools, though we do make use of them. + +If, after following this guide, you're still having issues getting an answer +file working, We recommend you read the official documentation on +[answer files](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/update-windows-settings-and-scripts-create-your-own-answer-file-sxs). + +The guide here is hopefully enough to get you started, but isn't a replacement +for the official documentation. + +## When To Use an Answer File + +If you are installing the Windows Operating System from a mounted iso as part of +your Packer build, you will need to use an Answer file. For example, you're +building an image from scratch using the [vmware-iso](/docs/builders/vmware-iso.html), +[virtualbox-iso](/docs/builders/virtualbox-iso.html), or +[hyperv-iso](/docs/builders/hyperv-iso.html) builders. + +If you are not installing the operating system, you won't need to provide an +answer file. If you are using a pre-built image +in a cloud, you don't need to worry about Answer files. + +## How to make an Answer File + +You can either start from an example answer file from a known repo (take a look +at the examples links below), or you can generate one using an answer file +wizard by selecting New File > New Answer file on a Windows machine. +A comprehensive list of all the options you can set in an answer file can be +found [here](https://docs.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/components-b-unattend) + +## Where to put the Answer File + +Windows will automatically look for an autounattend.xml file on mounted drives. +Many users use the `floppy_files` option or a secondary mounted iso for +providing the answer file to their iso builders. + +You can also specify an unattend file to use by using the /unattend: option when +running Windows Setup (setup.exe) in your `boot_command`. + +## What does Packer _need_ the Answer File to do? + +Packer needs the Answer File to handle any questions that would normally be +answered interactively during a Windows installation. + +If you want to be able to use provisioners, the Answer file must also contain +a script that sets up SSH or WinRM so that Packer can connect to the instance. + +Finally, your Packer build will be much smoother if the Answer File handles or +disables windows updates rather than you tyring to run them using a Packer +provisioner. This is because the winrm communicator does not handle the +disconnects caused by automatic reboots in Windows updates well, and the +disconnections can fail a build. + +## Examples + +The chef-maintained bento boxes are a great example of a windows build that +sets up openssh as part of the unattended installation so that Packer can +connect using the ssh communicator. They functioning answer files for every +modern Windows version. +https://github.com/chef/bento/tree/master/packer_templates/windows/answer_files + +Stefan Scherer's packer-windows repo is a great example of windows builds that +set up WinRM as part of the unattended installation so that Packer can connect +using the winrm communicator: +https://github.com/StefanScherer/packer-windows + +``` json + { + "type": "virtualbox-iso", + "guest_os_type": "Windows2008_64", + "iso_url": "https://download.microsoft.com/download/7/5/E/75EC4E54-5B02-42D6-8879-D8D3A25FBEF7/7601.17514.101119-1850_x64fre_server_eval_en-us-GRMSXEVAL_EN_DVD.iso", + "iso_checksum": "30832AD76CCFA4CE48CCB936EDEFE02079D42FB1DA32201BF9E3A880C8ED6312", + "iso_checksum_type": "sha256", + "shutdown_command": "shutdown /s /t 10 /f /d p:4:1 /c Packer_Provisioning_Shutdown", + "guest_additions_mode": "attach", + "floppy_files": [ + "./scripts/Autounattend.xml", + "./scripts/openssh.ps1" + ], + "communicator": "winrm", + "winrm_username": "vagrant", + "winrm_password": "vagrant" + } +``` \ No newline at end of file diff --git a/website/source/guides/automatic-operating-system-installs/index.html.md b/website/source/guides/automatic-operating-system-installs/index.html.md new file mode 100644 index 000000000..b5f711e2e --- /dev/null +++ b/website/source/guides/automatic-operating-system-installs/index.html.md @@ -0,0 +1,26 @@ +--- +layout: guides +sidebar_current: automatic-operating-system-installs +page_title: Automatic OS Installs +description: |- + Learn how to use preseed, kickstart, and autounattend files to automatically + answer installation questions and enable Packer to connect to your instnace. +--- + +# Automatic OS Installs + +If you are building from a brand-new and unconfigured operating system +image, Packer will need you to perform the operating system install before it +can connect to and configure your image using its provisioners. Most operating +system distributions have a mechanism for performing the normally-interactive +installation in an automated way. For Debian operating systems, this is done +using a preseed file; for Windows, it's done using an Autounattend.xml. We have +compiled some simple guides here for common operating system distributions. + +These guides are meant to give you a quick introduction to how to use automated +installation answer files in order to perfom those installs; we don't mean to +be a comprehensive guide on each operating system, but we hope to give you +enough context to be able to more easily find any further information you need. + +Please use the left-hand navigation to find instructions for the operating +system that is relevant to you. \ No newline at end of file diff --git a/website/source/guides/automatic-operating-system-installs/preseed_ubuntu.html.md b/website/source/guides/automatic-operating-system-installs/preseed_ubuntu.html.md new file mode 100644 index 000000000..3c55c4162 --- /dev/null +++ b/website/source/guides/automatic-operating-system-installs/preseed_ubuntu.html.md @@ -0,0 +1,179 @@ +--- +layout: guides +sidebar_current: automatic-operating-system-installs-unattended-installation-debian +page_title: Unattended Debian/Ubuntu Installation +description: |- + Learn how to use a preseed file to automatically answer installation + questions and enable Packer to connect to your Debian instnace. +--- + +# Unattended Installation for Debian + +Unattended Debian/Ubuntu installation is done via "preseed" files + +These files are generally named "preseed.cfg". They are not +Packer-specific tools, though we do make use of them. + +If, after following this guide, you're still having issues getting a preseed +file working, We recommend you read the official documentation on +[preseed files](https://wiki.debian.org/DebianInstaller/Preseed). + +The guide here is hopefully enough to get you started, but isn't a replacement +for the official documentation. + +## When To Use a Preseed File + +If you are installing the operating system from a mounted iso as part of +your Packer build, you will need to use a preseed file. For example, you're +building an image from scratch using the [vmware-iso](/docs/builders/vmware-iso.html), +[virtualbox-iso](/docs/builders/virtualbox-iso.html), or +[hyperv-iso](/docs/builders/hyperv-iso.html) builders. + +If you are not installing the operating system, you won't need to provide a +preseed file. If you are using a pre-built image in a cloud, you don't need to +worry about preseed files. + +## How to make a Preseed File + +You can either start from an example preseed file from a known repo (take a look +at the examples links below), or you can start with the official [example +preseed](https://www.debian.org/releases/stable/example-preseed.txt), and +comment or uncomment the options as you need them. + +## Where to put the preseed file + +The `-iso` builders mentioned above all have an `http_dir` option. Any file +inside of your `http_dir` will be served on a local fileserver for your virtual +machine to be able to access. One very common use for this directory is to use +it to provide your preseed file. + +You then reference the file using a `boot_command` to kick off the installation. +In the example below, see how the `preseed/url` command line option is being +used in the `/install/vmlinuz command`. The `{{ .HTTPIP }}` and +`{{ .HTTPPort }}` options are special Packer template options that will get set +by Packer to point to the http server we create, so that your boot command can +access it. For an example of a working boot_command, see the Examples section +below. For more information on how boot_command works, see the +boot_command section of the docs for whatever builder you are using. + +## What does Packer _need_ the preseed file to do? + +Packer needs the preseed file to handle any questions that would normally be +answered interactively during a Debian installation. + +If you want to be able to use provisioners, the preseed file must also install +SSH so that Packer can connect to the instance. + +## Examples + +A very minimal example of a preseed file can be found below. Much of this was +copied from the official example-preseed shared above. Notice that we are +installing ssh via `d-i pkgsel/include string openssh-server` and configuring +a username so that Packer will be able to connect. + +You need to make sure that your mirror settings are properly configured for your +specific distribution of Debian. + +``` +# Preseeding only locale sets language, country and locale. +d-i debian-installer/locale string en_US + +# Keyboard selection. +d-i console-setup/ask_detect boolean false +d-i keyboard-configuration/xkb-keymap select us + +choose-mirror-bin mirror/http/proxy string + +### Clock and time zone setup +d-i clock-setup/utc boolean true +d-i time/zone string UTC + +# Avoid that last message about the install being complete. +d-i finish-install/reboot_in_progress note + +# This is fairly safe to set, it makes grub install automatically to the MBR +# if no other operating system is detected on the machine. +d-i grub-installer/only_debian boolean true + +# This one makes grub-installer install to the MBR if it also finds some other +# OS, which is less safe as it might not be able to boot that other OS. +d-i grub-installer/with_other_os boolean true + +### Mirror settings +# If you select ftp, the mirror/country string does not need to be set. +d-i mirror/country string manual +d-i mirror/http/directory string /ubuntu/ +d-i mirror/http/hostname string archive.ubuntu.com +d-i mirror/http/proxy string + +### Partitioning +d-i partman-auto/method string lvm + +# This makes partman automatically partition without confirmation. +d-i partman-md/confirm boolean true +d-i partman-partitioning/confirm_write_new_label boolean true +d-i partman/choose_partition select finish +d-i partman/confirm boolean true +d-i partman/confirm_nooverwrite boolean true + +### Account setup +d-i passwd/user-fullname string vagrant +d-i passwd/user-uid string 1000 +d-i passwd/user-password password vagrant +d-i passwd/user-password-again password vagrant +d-i passwd/username string vagrant + +# The installer will warn about weak passwords. If you are sure you know +# what you're doing and want to override it, uncomment this. +d-i user-setup/allow-password-weak boolean true +d-i user-setup/encrypt-home boolean false + +### Package selection +tasksel tasksel/first standard +d-i pkgsel/include string openssh-server build-essential +d-i pkgsel/install-language-support boolean false + +# disable automatic package updates +d-i pkgsel/update-policy select none +d-i pkgsel/upgrade select full-upgrade +``` + +Here's an example of the vmware-iso builder being used to call this preseed. +In this case, it is assumed that the file is saved as preseed.cfg inside of a +directory called "http", and Packer is being called from the directory +containing the "http" directory. + +``` + "builders": [ + { + "boot_command": [ + "", + "", + "", + "/install/vmlinuz", + " initrd=/install/initrd.gz", + " auto-install/enable=true", + " debconf/priority=critical", + " preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed_2.cfg", + " -- ", + "" + ], + "boot_wait": "10s", + "guest_os_type": "ubuntu-64", + "http_directory": "http", + "iso_checksum_type": "sha256", + "iso_checksum_url": "file:///Users/mmarsh/dev/repro_cases/packer_cache/shasums.txt", + "iso_url": "http://old-releases.ubuntu.com/releases/14.04.1/ubuntu-14.04.1-server-amd64.iso", + "shutdown_command": "echo 'vagrant' | sudo -S shutdown -P now", + "ssh_password": "vagrant", + "ssh_username": "vagrant", + "ssh_wait_timeout": "10000s", + "tools_upload_flavor": "linux", + "type": "vmware-iso" + } + ], +``` + +For more functional examples of a debian preseeded installation, you can see the +Chef-maintained bento boxes for [Debian](https://github.com/chef/bento/tree/master/packer_templates/debian) +and [Ubuntu](https://github.com/chef/bento/tree/master/packer_templates/ubuntu) \ No newline at end of file diff --git a/website/source/guides/workflow-tips-and-tricks/index.html.md b/website/source/guides/workflow-tips-and-tricks/index.html.md new file mode 100644 index 000000000..6a513ea28 --- /dev/null +++ b/website/source/guides/workflow-tips-and-tricks/index.html.md @@ -0,0 +1,13 @@ +--- +layout: guides +sidebar_current: workflow-tips-and-tricks +page_title: Tips and Tricks +description: |- + The guides stored in this section are miscellanious tips and tricks that might + make your experience of using Packer easier +--- + +# Tips and Tricks + +Click the sidebar navigation to check out the miscellaneous guides we have for +making your life with Packer just a bit easier. diff --git a/website/source/guides/isotime-template-function.html.md b/website/source/guides/workflow-tips-and-tricks/isotime-template-function.html.md similarity index 96% rename from website/source/guides/isotime-template-function.html.md rename to website/source/guides/workflow-tips-and-tricks/isotime-template-function.html.md index 48c084704..7eacf521e 100644 --- a/website/source/guides/isotime-template-function.html.md +++ b/website/source/guides/workflow-tips-and-tricks/isotime-template-function.html.md @@ -1,6 +1,6 @@ --- layout: guides -sidebar_current: isotime-template-function +sidebar_current: workflow-tips-and-tricks-isotime-template-function page_title: Using the isotime template function - Guides description: |- It can be a bit confusing to figure out how to format your isotime using the diff --git a/website/source/guides/use-packer-with-comment.html.md b/website/source/guides/workflow-tips-and-tricks/use-packer-with-comment.html.md similarity index 96% rename from website/source/guides/use-packer-with-comment.html.md rename to website/source/guides/workflow-tips-and-tricks/use-packer-with-comment.html.md index 52fbaa7dc..e3176653e 100644 --- a/website/source/guides/use-packer-with-comment.html.md +++ b/website/source/guides/workflow-tips-and-tricks/use-packer-with-comment.html.md @@ -1,6 +1,6 @@ --- layout: guides -sidebar_current: use-packer-with-comment +sidebar_current: workflow-tips-and-tricks-use-packer-with-comment page_title: Use jq and Packer to comment your templates - Guides description: |- You can add detailed comments beyond the root-level underscore-prefixed field diff --git a/website/source/guides/veewee-to-packer.html.md b/website/source/guides/workflow-tips-and-tricks/veewee-to-packer.html.md similarity index 97% rename from website/source/guides/veewee-to-packer.html.md rename to website/source/guides/workflow-tips-and-tricks/veewee-to-packer.html.md index 710cbae72..5c4c7a3d7 100644 --- a/website/source/guides/veewee-to-packer.html.md +++ b/website/source/guides/workflow-tips-and-tricks/veewee-to-packer.html.md @@ -1,6 +1,6 @@ --- layout: guides -sidebar_current: guides-veewee-to-packer +sidebar_current: workflow-tips-and-tricks-guides-veewee-to-packer page_title: Convert Veewee Definitions to Packer Templates - Guides description: |- If you are or were a user of Veewee, then there is an official tool called diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 11c9f8a49..6593ae9f9 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -53,6 +53,18 @@
+ > + Communicators + + + > Builders