Start or stop an SFTP server

You can stop or start an SFTP server to manage its state, control access, and help optimize costs.

Stopping a server disables access and reduces resource usage. For example, if you suspect unauthorized access to a server, you can halt all active transfers and block new connections by stopping the server. As another example, you can reduce server uptime costs by pausing a server during periods when no data transfers are expected.

When you start a server, access is restored and users can connect to the server.

Required roles

To get the permission that you need to start or stop an SFTP server, ask your administrator to grant you the Cloud FTP Admin (roles/ftp.admin) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the ftp.servers.update permission, which is required to start or stop an SFTP server.

You might also be able to get this permission with custom roles or other predefined roles.

Stop a server

When you stop a server, the following things happen:

• Access is denied and active connections are dropped. Users who have an active connection might see an error message like the following:

  Connection is terminated: Connection closed by remote host
  client_loop: send disconnect: Broken pipe
  Connection closed
  

• No new connections can be established.

To stop a server, use the following steps.

REST

To stop a server, use the servers.stop method.

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID of the server.
• LOCATION_ID: the Google Cloud location of the server, such as us-west1.
• SERVER_ID: the server ID.

HTTP method and URL:

POST https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID:stop

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID:stop"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID:stop" | Select-Object -Expand Content

The response identifies a long-running operation.

Client libraries

C#

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP C# API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.Ftp.V1;
using Google.LongRunning;
using System.Threading.Tasks;

public sealed partial class GeneratedCloudFtpClientSnippets
{
    /// <summary>Snippet for StopServerAsync</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task StopServerAsync()
    {
        // Create client
        CloudFtpClient cloudFtpClient = await CloudFtpClient.CreateAsync();
        // Initialize request argument(s)
        string name = "projects/[PROJECT]/locations/[LOCATION]/servers/[SERVER]";
        // Make the request
        Operation<Server, OperationMetadata> response = await cloudFtpClient.StopServerAsync(name);

        // Poll until the returned long-running operation is complete
        Operation<Server, OperationMetadata> completedResponse = await response.PollUntilCompletedAsync();
        // Retrieve the operation result
        Server result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Server, OperationMetadata> retrievedResponse = await cloudFtpClient.PollOnceStopServerAsync(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Server retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Go API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

//go:build examples

package main

import (
	"context"

	ftp "cloud.google.com/go/ftp/apiv1"
	ftppb "cloud.google.com/go/ftp/apiv1/ftppb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := ftp.NewCloudFtpRESTClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &ftppb.StopServerRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/ftp/apiv1/ftppb#StopServerRequest.
	}
	op, err := c.StopServer(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Java API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.api.core.ApiFuture;
import com.google.cloud.ftp.v1.CloudFtpClient;
import com.google.cloud.ftp.v1.ServerName;
import com.google.cloud.ftp.v1.StopServerRequest;
import com.google.longrunning.Operation;

public class AsyncStopServer {

  public static void main(String[] args) throws Exception {
    asyncStopServer();
  }

  public static void asyncStopServer() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (CloudFtpClient cloudFtpClient = CloudFtpClient.create()) {
      StopServerRequest request =
          StopServerRequest.newBuilder()
              .setName(ServerName.of("[PROJECT]", "[LOCATION]", "[SERVER]").toString())
              .build();
      ApiFuture<Operation> future = cloudFtpClient.stopServerCallable().futureCall(request);
      // Do something.
      Operation response = future.get();
    }
  }
}

Node.js

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Node.js API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Name of the resource.
 *  Format: `projects/{project}/locations/{location}/servers/{server}`
 */
// const name = 'abc123'

// Imports the Ftp library
const {CloudFtpClient} = require('@google-cloud/ftp').v1;

// Instantiates a client
const ftpClient = new CloudFtpClient();

async function callStopServer() {
  // Construct request
  const request = {
    name,
  };

  // Run request
  const [operation] = await ftpClient.stopServer(request);
  const [response] = await operation.promise();
  console.log(response);
}

callStopServer();

PHP

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP PHP API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\ApiCore\ApiException;
use Google\ApiCore\OperationResponse;
use Google\Cloud\Ftp\V1\Client\CloudFtpClient;
use Google\Cloud\Ftp\V1\Server;
use Google\Cloud\Ftp\V1\StopServerRequest;
use Google\Rpc\Status;

/**
 * Stops an active Server.
 *
 * @param string $formattedName Name of the resource.
 *                              Format: `projects/{project}/locations/{location}/servers/{server}`
 *                              Please see {@see CloudFtpClient::serverName()} for help formatting this field.
 */
function stop_server_sample(string $formattedName): void
{
    // Create a client.
    $cloudFtpClient = new CloudFtpClient();

    // Prepare the request message.
    $request = (new StopServerRequest())
        ->setName($formattedName);

    // Call the API and handle any network failures.
    try {
        /** @var OperationResponse $response */
        $response = $cloudFtpClient->stopServer($request);
        $response->pollUntilComplete();

        if ($response->operationSucceeded()) {
            /** @var Server $result */
            $result = $response->getResult();
            printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString());
        } else {
            /** @var Status $error */
            $error = $response->getError();
            printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedName = CloudFtpClient::serverName('[PROJECT]', '[LOCATION]', '[SERVER]');

    stop_server_sample($formattedName);
}

Python

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Python API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import ftp_v1


def sample_stop_server():
    # Create a client
    client = ftp_v1.CloudFtpClient()

    # Initialize request argument(s)
    request = ftp_v1.StopServerRequest(
        name="name_value",
    )

    # Make the request
    operation = client.stop_server(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Ruby API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/ftp/v1"

##
# Snippet for the stop_server call in the CloudFtp service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::Ftp::V1::CloudFtp::Rest::Client#stop_server.
#
def stop_server
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::Ftp::V1::CloudFtp::Rest::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::Ftp::V1::StopServerRequest.new

  # Call the stop_server method.
  result = client.stop_server request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

Start a server

REST

To start a server, use the servers.start method.

Before using any of the request data, make the following replacements:

• PROJECT_ID: the Google Cloud project ID of the server.
• LOCATION_ID: the Google Cloud location of the server, such as us-west1.
• SERVER_ID: the server ID.

HTTP method and URL:

POST https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID:start

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID:start"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://ftp.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/servers/SERVER_ID:start" | Select-Object -Expand Content

The response identifies a long-running operation. It takes a few minutes for the server to start.

Client libraries

C#

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP C# API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

using Google.Cloud.Ftp.V1;
using Google.LongRunning;
using System.Threading.Tasks;

public sealed partial class GeneratedCloudFtpClientSnippets
{
    /// <summary>Snippet for StartServerAsync</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task StartServerAsync()
    {
        // Create client
        CloudFtpClient cloudFtpClient = await CloudFtpClient.CreateAsync();
        // Initialize request argument(s)
        string name = "projects/[PROJECT]/locations/[LOCATION]/servers/[SERVER]";
        // Make the request
        Operation<Server, OperationMetadata> response = await cloudFtpClient.StartServerAsync(name);

        // Poll until the returned long-running operation is complete
        Operation<Server, OperationMetadata> completedResponse = await response.PollUntilCompletedAsync();
        // Retrieve the operation result
        Server result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Server, OperationMetadata> retrievedResponse = await cloudFtpClient.PollOnceStartServerAsync(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Server retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Go API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

//go:build examples

package main

import (
	"context"

	ftp "cloud.google.com/go/ftp/apiv1"
	ftppb "cloud.google.com/go/ftp/apiv1/ftppb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := ftp.NewCloudFtpRESTClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &ftppb.StartServerRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/ftp/apiv1/ftppb#StartServerRequest.
	}
	op, err := c.StartServer(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Java API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.api.core.ApiFuture;
import com.google.cloud.ftp.v1.CloudFtpClient;
import com.google.cloud.ftp.v1.ServerName;
import com.google.cloud.ftp.v1.StartServerRequest;
import com.google.longrunning.Operation;

public class AsyncStartServer {

  public static void main(String[] args) throws Exception {
    asyncStartServer();
  }

  public static void asyncStartServer() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (CloudFtpClient cloudFtpClient = CloudFtpClient.create()) {
      StartServerRequest request =
          StartServerRequest.newBuilder()
              .setName(ServerName.of("[PROJECT]", "[LOCATION]", "[SERVER]").toString())
              .build();
      ApiFuture<Operation> future = cloudFtpClient.startServerCallable().futureCall(request);
      // Do something.
      Operation response = future.get();
    }
  }
}

Node.js

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Node.js API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Name of the resource
 *  Format: `projects/{project}/locations/{location}/servers/{server}`
 */
// const name = 'abc123'

// Imports the Ftp library
const {CloudFtpClient} = require('@google-cloud/ftp').v1;

// Instantiates a client
const ftpClient = new CloudFtpClient();

async function callStartServer() {
  // Construct request
  const request = {
    name,
  };

  // Run request
  const [operation] = await ftpClient.startServer(request);
  const [response] = await operation.promise();
  console.log(response);
}

callStartServer();

PHP

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP PHP API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\ApiCore\ApiException;
use Google\ApiCore\OperationResponse;
use Google\Cloud\Ftp\V1\Client\CloudFtpClient;
use Google\Cloud\Ftp\V1\Server;
use Google\Cloud\Ftp\V1\StartServerRequest;
use Google\Rpc\Status;

/**
 * Starts a stopping/stopped Server.
 *
 * @param string $formattedName Name of the resource
 *                              Format: `projects/{project}/locations/{location}/servers/{server}`
 *                              Please see {@see CloudFtpClient::serverName()} for help formatting this field.
 */
function start_server_sample(string $formattedName): void
{
    // Create a client.
    $cloudFtpClient = new CloudFtpClient();

    // Prepare the request message.
    $request = (new StartServerRequest())
        ->setName($formattedName);

    // Call the API and handle any network failures.
    try {
        /** @var OperationResponse $response */
        $response = $cloudFtpClient->startServer($request);
        $response->pollUntilComplete();

        if ($response->operationSucceeded()) {
            /** @var Server $result */
            $result = $response->getResult();
            printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString());
        } else {
            /** @var Status $error */
            $error = $response->getError();
            printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedName = CloudFtpClient::serverName('[PROJECT]', '[LOCATION]', '[SERVER]');

    start_server_sample($formattedName);
}

Python

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Python API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import ftp_v1


def sample_start_server():
    # Create a client
    client = ftp_v1.CloudFtpClient()

    # Initialize request argument(s)
    request = ftp_v1.StartServerRequest(
        name="name_value",
    )

    # Make the request
    operation = client.start_server(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

To learn how to install and use the client library for Cloud FTP, see Cloud FTP client libraries. For more information, see the Cloud FTP Ruby API reference documentation.

To authenticate to Cloud FTP, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

require "google/cloud/ftp/v1"

##
# Snippet for the start_server call in the CloudFtp service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::Ftp::V1::CloudFtp::Rest::Client#start_server.
#
def start_server
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::Ftp::V1::CloudFtp::Rest::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::Ftp::V1::StartServerRequest.new

  # Call the start_server method.
  result = client.start_server request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

What's next

• Delete users from an SFTP server
• Delete an SFTP server