Knowledge Base

The VMware Knowledge Base provides support solutions, error messages and troubleshooting guides
 
Search the VMware Knowledge Base (KB)   View by Article ID
 

Creating a persistent scratch location for ESXi 4.x and 5.x (1033696)

Symptoms

  • When you run the esxcli software vib list command, you see an error similar to:

    Traceback (most recent call last):
    File "/usr/lib/vmware/esxcli-software", line 432, in <module>
    setupLogging()
    File "/usr/lib/vmware/esxcli-software", line 78, in setupLogging
    handler = logging.handlers.SysLogHandler(address='/dev/log')
    File "/build/mts/release/bora-504890/bora/build/esx/release/python-
    2.6-lib-zip-stage/504890/visor/pylib/python2.6/logging/handlers.py",
    line 704, in __init__
    File "/build/mts/release/bora-504890/bora/build/esx/release/python-
    2.6-lib-zip-stage/504890/visor/pylib/python2.6/logging/handlers.py",
    line 719, in _connect_unixsocket
    File "<string>", line 1, in connect
    socket.error: [Errno 2] No such file or directory

  • Commands related to esxcli software or esxupdate do not work.
  • Scanning the host using Update Manager fails with the error:

    General System Error

  • Rebooting the host initially resolves the issue, but it reoccurs in a few days.
  • Log files are missing in /var/log/ or are not being updated.
  • You cannot install HA agent on affected ESXi hosts.
  • ESXi is installed on a SD card or USB stick.

Purpose

This article describes the procedure to create a persistent scratch location for ESXi.

VMware recommends that ESXi has a persistent scratch location available for storing temporary data including logs, diagnostic information, and system swap. (This is not a requirement, however.) Persistent scratch space may be provisioned on a FAT 16, VMFS, or NFS partition accessible by the ESXi host.

Note: Scratch space is configured automatically during installation or first boot of an ESXi host, and does not usually need to be manually configured. ESXi Installable creates a 4 GB Fat16 partition on the target device during installation if there is sufficient space, and if the device is considered Local.

Starting with VirtualCenter 2.5 Update 1, only ESXi systems with swap enabled can be added to an HA cluster. For more information, see ESXi hosts without swap enabled cannot be added to a VMware High Availability Cluster (1004177).

Cause

If persistent scratch space is not available, ESXi stores this temporary data on a ramdisk, which is constrained in space. This might be problematic in low-memory situations, but is not critical to the operation of ESXi. Information stored on a ramdisk does not persist across reboots, so troubleshooting information such as logs and core files could be lost. If a persistent scratch location on the host is not configured properly, you may experience intermittent issues due to lack of space for temporary files and the log files will not be updated.

Scratch space is configured automatically during installation or first boot of an ESXi 4.1 U2 and later host, and does not usually need to be manually configured. For more details, see the Additional Information section of this article.

Resolution

Scratch space can be manually configured for an ESXi host using the vSphere Client, the vCLI, PowerCLI, Tech Support Mode, or during scripted installation. Select the method appropriate to your environment. Regardless of the method selected, the configuration is written to the /etc/vmware/locker.conf configuration file for use during the next boot.

Changing the configured scratch location requires a reboot of the ESXi host for the changes to take effect. Use vMotion to migrate or power off all virtual machines on the ESXi host prior to making the change. For more information, see Rebooting an ESX Server host (1003530).

The configured scratch location must point to a directory on a filesystem accessible to the ESXi host, such as a Fat16 or VMFS volume. The location may be a directory on a shared or remote disk as long as the ESXi host is allocated its own separate directory.

Caution: Do not share a scratch locker directory among multiple ESXi hosts.

Note: It is not supported to configure a scratch location on a VSAN datastore.

It may be necessary to do a reboot of the ESXi host before completing these procedures.

Configuring a persistent scratch location using the vSphere Client

To configure persistent scratch space for ESXi using the vSphere Client:
  1. Connect to vCenter Server or the ESXi host using the vSphere Client.
  2. Click the ESXi host in the inventory.
  3. Under the Configuration tab, click Storage.
  4. Right-click a datastore and click Browse.
  5. Create a uniquely-named directory for this ESXi host (for example, .locker-ESXHostname).
  6. Close the Datastore Browser.
  7. Click Advanced Settings under Software.
  8. Select the ScratchConfig section.
  9. Change the ScratchConfig.ConfiguredScratchLocation configuration option, specifying the full path to the directory. For example:

    /vmfs/volumes/DatastoreUUID/.locker-ESXHostname

    Note: To determine the Datastore UUID:
    1. Navigate to Configuration > Storage.
    2. Select the datastore.
    3. View Location under Datastore Details.

      The Datastore UUID appears similar to /vmfs/volumes/51dda02d-fade5016-8a08-005056171889 where 51dda02d-fade5016-8a08-005056171889 is the UUID.

  10. Click OK.
  11. Put the ESXi host into maintenance mode and reboot for the configuration change to take effect.

Configuring a persistent scratch location using the vCLI

To configure persistent scratch space for ESXi using the vSphere Command-Line Interface:

Note: For more information on usage, see the vSphere Command-Line Interface Documentation.
  1. Open a command prompt at the location where the vCLI is installed.
  2. Obtain a list of datastores reachable from this ESXi host using the command:

    vifs.pl connectoptions --listds

    For example:

    vifs.pl --server esx_hostname_or_IP --username root --listds

  3. Create a uniquely-named directory for this ESXi host using the command:

    vifs.pl connectoptions --mkdir "[DatastoreName] DirectoryName"

    For example:

    vifs.pl --server esx_hostname_or_IP --username root --mkdir "[Datastore1] .locker-ESXHostname"

  4. Check the current value of the ScratchConfig.ConfiguredScratchLocation configuration option using the command:

    vicfg-advcfg.pl connectoptions -g ScratchConfig.ConfiguredScratchLocation

    For example:

    vicfg-advcfg.pl --server esx_hostname_or_IP --username root -g ScratchConfig.ConfiguredScratchLocation
    Value of ScratchConfig.ConfiguredScratchLocation is /path/to/location


  5. Change the ScratchConfig.ConfiguredScratchLocation configuration option, specifying the full path to the directory created in step 3, using the command:

    vicfg-advcfg.pl connectoptions -s /vmfs/volumes/DatastoreName/DirectoryName ScratchConfig.ConfiguredScratchLocation

    For example:

    vicfg-advcfg.pl --server esx_hostname_or_IP --username root -s /vmfs/volumes/Datastore1/.locker-ESXHostname ScratchConfig.ConfiguredScratchLocation

  6. Put the ESXi host into maintenance mode and reboot for the configuration change to take effect.

Configuring a persistent scratch location using PowerCLI

To configure persistent scratch space for ESXi using the vSphere PowerCLI interface:

Notes:
  • Before proceeding, ensure that /tmp/scratch exists. If it does not exist, use the command mkdir /tmp/scratch to create it.
  • For more information on vSphere PowerCLI usage, see the vSphere PowerCLI documentation.
  1. Open a command prompt where the PowerCLI is installed.
  2. Connect to the ESXi host using the command:

    connect-viserver esx_hostname_or_IP

  3. Obtain a list of datastores reachable from this ESXi host using the command:

    Get-Datastore

  4. Mount a datastore read/write as a PSDrive using the command:

    New-PSDrive -Name "mounteddatastore" -Root \ -PSProvider VimDatastore -Datastore (Get-Datastore "DatastoreName")

  5. Access the new PSDrive using the command:

    Set-Location mounteddatastore:

  6. Create a uniquely-named directory for this ESXi host using the command:

    New-Item "DirectoryName" -ItemType directory

    For example:

    New-Item ".locker-ESXHostname" -ItemType directory

  7. Check the current value of the ScratchConfig.ConfiguredScratchLocation configuration option using the command:

    Get-VMHostAdvancedConfiguration -Name "ScratchConfig.ConfiguredScratchLocation"

    Note: VMHostAdvancedConfiguration has been deprecated in PowerCLI 5.1 and replaced with AdvancedSetting. For more information, see the vSphere PowerCLI documentation.

  8. Change the ScratchConfig.ConfiguredScratchLocation configuration option, specifying the full path to the directory created in step 6, using the command:

    Set-VMHostAdvancedConfiguration -Name "ScratchConfig.ConfiguredScratchLocation" -Value "/vmfs/volumes/DatastoreName/DirectoryName"

    For example:

    Set-VMHostAdvancedConfiguration -Name "ScratchConfig.ConfiguredScratchLocation" -Value "/vmfs/volumes/Datastore1/.locker-ESXHostname"

  9. Put the ESXi host into maintenance mode and reboot for the configuration change to take effect.

Configuring a persistent scratch location using Tech Support Mode

To configure persistent scratch space for ESXi using Tech Support Mode on ESXi:

Notes:
  • This can be done either via the local console or SSH.
  • A .filename is a hidden file. To view hidden files, use the ls -a command.
  1. Open a console to the ESXi host. For more information, see Using Tech Support Mode in ESXi 4.1 and 5.0 (1017910).
  2. Obtain a list of datastores reachable from this ESXi host using the command:

    ls /vmfs/volumes

  3. Create a uniquely-named directory for this ESXi host using the command:

    mkdir /vmfs/volumes/DatastoreName/DirectoryName

    For example:

    mkdir /vmfs/volumes/Datastore1/.locker-ESXHostname

  4. Check the current value of the ScratchConfig.ConfiguredScratchLocation configuration option using the command:

    vim-cmd hostsvc/advopt/view ScratchConfig.ConfiguredScratchLocation

    Example output:

    (vim.option.OptionValue) [
    (vim.option.OptionValue) {
    dynamicType = <unset>,
    key = "ScratchConfig.ConfiguredScratchLocation",
    value = "/path/to/location",
    }
    }


  5. Change the ScratchConfig.ConfiguredScratchLocation configuration option, specifying the full path to the directory created in step 3, using the command:

    vim-cmd hostsvc/advopt/update ScratchConfig.ConfiguredScratchLocation string /vmfs/volumes/DatastoreName/DirectoryName

    For example:

    /bin/vim-cmd hostsvc/advopt/update ScratchConfig.ConfiguredScratchLocation string /vmfs/volumes/Datastore1/.locker-ESXHostname

  6. Put the ESXi host into maintenance mode and reboot for the configuration change to take effect.

Configuring a persistent scratch location during scripted install using kickstart scripts

You can configure persistent scratch space for ESXi during kickstart installation by adding commands to your kickstart scripts which create the directory and change the configuration option. For more information on ESXi scripted deployments, see the ESXi Installable and vCenter Server Setup Guide.

Append these commands to your custom kickstart script:
# Generate a new scratch directory for this host on a Datastore
scratchdirectory=/vmfs/volumes/DatastoreName/.locker-$(hostname 2> /dev/null)-$(esxcfg-info -b 2> /dev/null)

# Create the scratch directory
mkdir -p $scratchdirectory

# Change the advanced configuration option
vim-cmd hostsvc/advopt/update ScratchConfig.ConfiguredScratchLocation string $scratchdirectory
Note: The configured scratch location is activated during startup of the ESXi host. A reboot is required after performing the preceding commands.

Configuring a persistent scratch location using the vSphere Web Client for ESXi 5.1 and 5.5

To configure persistent scratch space for ESXi using the vSphere Web Client:
  1. Log in to the vCenter Server using the vSphere Web Client.
  2. Click Hosts and Clusters, then click the specific host.
  3. Under the Manage tab, click Settings.
  4. Under System, click Advanced System Settings.
  5. Locate ScratchConfig.ConfiguredScratchLocation.
  6. Click Edit and add the path to the scratch directory.
  7. Reboot the host for the changes to take effect.


Additional Information

For information regarding a known issue when upgrading a Cisco Nexus 1000V module on a host that has NFS-backed scratch, see Cannot upgrade Cisco Nexus 1000V module on ESXi host configured with NFS backed scratch (2004978).

For more information on the scratch partition, see:

If the host has been running for more than 24 hours, this setting may not stay persistent after performing the preceding steps. In this case, perform these steps:
  1. Place the host into Maintenance Mode and reboot the host.
  2. Click the Configuration tab.
  3. Click Software.
  4. Click Advanced Settings.
  5. Select the ScratchConfig section.
  6. Change the ScratchConfig.ConfiguredScratchLocation configuration option and set it to the full path of the directory.

    For example:

    /vmfs/volumes/DatastoreName/.locker-ESXHostname

  7. Click OK.
  8. Close the window.
  9. Click Advanced Settings to reopen the window.
  10. Select the ScratchConfig section.
  11. Verify that the ScratchConfig.ConfiguredScratchLocation field contains the scratch setting that you configured in step 6. If it does, reboot the host.

    The host is now using the configured scratch partition.

For more information on determining whether a disk device is considered Local, see Identifying disks when working with VMware ESX (1014953), and review the Is Local flag in the output of the esxcfg-scsidevs -l command:
  • If Local is true, the storage device is not sharable among multiple ESXi hosts.
  • If Local is false, the storage device is remote and potentially sharable among several ESXi hosts. Remote devices are not automatically used for scratch by ESXi.

ESXi selects one of these scratch locations during startup in this order of preference:
  1. The location configured in the /etc/vmware/locker.conf configuration file, set by the ScratchConfig.ConfiguredScratchLocation configuration option, as in this article
  2. A Fat16 filesystem of at least 4 GB on the Local Boot device
  3. A Fat16 filesystem of at least 4 GB on a Local device
  4. A VMFS datastore on a Local device, in a .locker/ directory
  5. A ramdisk at /tmp/scratch/
These are two examples where scratch space may not be automatically defined on persistent storage. In each case, the temporary scratch location will be configured on a ramdisk:
  • ESXi deployed on a Flash or SD device, including a USB key. Scratch partitions are not created on Flash or SD storage devices even if connected during install, due to the potentially limited read/write cycles available.
  • ESXi deployed in a Boot from SAN configuration or to a SAS device. A Boot from SAN or SAS LUN is considered Remote, and could potentially be shared among multiple ESXi hosts. Remote devices are not used for scratch to avoid collisions between multiple ESXi hosts.

For information on configuring syslog on ESXi 5.x, see Configuring syslog on ESXi 5.x (2003322).

For translated versions of this article, see:

• Español: Crear una ubicación permanente para datos temporales en ESXi (2033130)
• Português: Como criar uma área de rascunho persistente para ESXi (2032967)
• 日本語: ESXi 4.x および ESX 5.x 環境での scratchの作成 (2042585)

Tags

scratch-partition

See Also

This Article Replaces

2012246

Update History

07/19/2012 - Added information that provisioning scratch space on a NFS partition is not recommended 07/19/2012 - Added [Hostname}.log to #10 of resolution. 07/20/2012 - Added Info regarding swal for ESXi and link to KB 1004177. 01/30/2013 - Added VMHostAdvancedConfiguration has been deprecated, replaced with AdvancedSetting 02/07/2013 - Removed NFS is not recommended. 10/21/2013 - Added ESXi 5.5 to Product Versions.

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 76 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.
What can we do to improve this information? (4000 or fewer characters)
  • 76 Ratings
Actions
KB: