Understanding initiateFileTransferFromGuest API Operations and Log Triggers

Products

• VMware vCenter Server

Issue/Introduction

While reviewing vCenter Server logs, you may encounter entries related to the vim.vm.guest.FileManager.initiateFileTransferFromGuest API,

For example:

####### - [Originator@6876 sub="vpxLro" opID="########-##"] [VpxLRO] -- BEGIN lro-###### -- guestOperationsFileManager -- vim.vm.guest.FileManager.initiateFileTransferFromGuest -- 220e52c7-####-####-####-f648bf2d7410

This KB explains the purpose of this API call, common scenarios that trigger these log entries, and how to identify the users who initiated these file transfer operations.

Environment

VMware vCenter Server

Resolution

What is the initiateFileTransferFromGuest API Operation?

The initiateFileTransferFromGuest API is part of the vSphere Guest Operations API. It allows vCenter Server (or a client connected to vCenter) to instruct VMware Tools (running inside a powered-on virtual machine) to retrieve a specified file from the guest operating system. The file is then staged for transfer from the ESXi host to the entity that initiated the API call.

When Do These Logs Trigger?

These log entries are generated whenever any authorized entity uses the vSphere API to retrieve a file from a VM's guest OS. This operation requires VMware Tools to be installed and running in the guest OS, and for the VM to be powered on.

Common operational scenarios that trigger these logs include:

• Manual Administrative Actions: An administrator using the vSphere Client's built-in "Download file from guest" feature to gather logs, configuration files, or other data for troubleshooting or auditing.
• Automated Scripts: Custom scripts (e.g., written in PowerCLI, Python pyvmomi, or other SDKs) that automate the collection of specific files from VMs or inventory, compliance, or diagnostic data collection.
• Third-Party Tools: Some backup and monitoring solutions may leverage Guest Operations to retrieve specific VM-level logs or configuration before/after backup tasks or as part of their health checks.
• Internal vCenter Server Operations: vCenter Server or other embedded vSphere services (e.g., vSphere Replication, VMware Update Manager, etc.) might use Guest Operations to interact with VMware Appliance VMs (like the vCenter Server Appliance itself, NSX Manager, HCX Manager) to collect logs for internal diagnostics or management purposes.

Who Initiates These API Calls?

This API call involves two distinct user layers:

1. The Initiating vCenter User/Service Account:

• • • The initiateFileTransferFromGuest API call is always initiated by a user or service account that has successfully authenticated to vCenter Server. This is an "actual user login" at the vCenter management layer.
    • This vCenter user (e.g., [email protected], DOMAIN\svc_account_backup, or any other assigned user) must have the Guest operation -> Guest operation file manipulation privilege assigned to them on the target VM or a parent inventory object.

2. The Guest OS User Account:

• • • When the vCenter user initiates the API call, they must also provide guest operating system credentials (a valid username and password) for an account inside the target VM.
    • VMware Tools, running inside the VM, uses these provided guest OS credentials to authenticate itself within the guest and then access the specified file. This guest OS user account must have sufficient permissions within the guest to read the target file.

How to Identify the Initiator?

The opID (e.g., ########-##) in the provided log entry is a key identifier. By searching vCenter Server's vpxd.log around the exact timestamp of the BEGIN lro entry, other log lines associated with the same opID will typically reveal which vCenter-level user account initiated this specific operation.

Additional Information

For best practices related to the StartProgramInGuest API, please refer to the following KB: Best practices for StartProgramInGuest API