Use Firewall Rules Logging

Firewall Rules Logging allows you to audit, verify, and analyze the effects of your firewall rules. For example, you can determine if a firewall rule designed to deny traffic is functioning as intended. Logging is also useful if you need to determine how many connections are affected by a given firewall rule.

This page shows you how to enable and disable logging for Virtual Private Cloud firewall rules. For instructions about logging for firewall policy rules, see Use hierarchical firewall policies and rules.

This page also shows you how to view generated logs. For more information about what is logged, examples of logging, and log formats, see Firewall Rules Logging.

If you enable logging on a firewall rule, you can view insights and recommendations for it from Firewall Insights. For more information, see Firewall Insights in the Network Intelligence Center documentation.

Permissions

To modify firewall rules or access logs, IAM principals need one of the following roles.

Task Required Role
Create, delete, or update firewall rules Project owner or editor or Security Admin
View Logs Project owner, editor or viewer or Logs Viewer
See the Logging Access Control Guide for details about Logging IAM roles and permissions.

Enable and disable Firewall Rules Logging

When you create a firewall rule, you can choose to turn on firewall rules logging. For more information, see Create firewall rules.

To enable or disable Firewall Rules Logging for an existing firewall rule, follow these directions. When you enable logging, you can control whether metadata fields are included. If you omit them, you can save on storage costs.

Enable Firewall Rules Logging

Console

  1. In the Google Cloud console, go to the Firewall policies page.

    Go to Firewall policies

  2. In the Logs column, determine if firewall logging is on or off for each firewall rule.

  3. To enable logging for one or more firewall rules, select the checkbox next to each rule that you want to update.

  4. In the VPC firewall rules action bar, click Configure logs.

  5. In the Configure logs dialog, select On.

  6. To omit the metadata fields, expand Show logs details, and then clear the Include metadata checkbox.

  7. Click Save configuration.

gcloud 

gcloud compute firewall-rules update RULE_NAME \
    --enable-logging \
    --logging-metadata=LOGGING_METADATA

Replace the following:

  • RULE_NAME: the name of the firewall rule.
  • LOGGING_METADATA: whether Firewall Rules Logging includes metadata fields in firewall rule logs. You can configure this field only if logging is enabled. The value must be exclude-all or include-all. By default, metadata fields are included.

For more information, see the SDK reference documentation.

Terraform

You can use the Terraform resource to create a firewall rule with logging enabled.

resource "google_compute_firewall" "rules" {
  project     = var.project_id # Replace this with your project ID in quotes
  name        = "my-firewall-rule"
  network     = "default"
  description = "Creates firewall rule targeting tagged instances"

  log_config {
    metadata = "INCLUDE_ALL_METADATA"
  }

  allow {
    protocol = "tcp"
    ports    = ["80", "8080", "1000-2000"]
  }
  target_tags = ["web"]
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

API

Enable Firewall Rules Logging for an existing firewall rule.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/firewalls/RULE_NAME
{
  "name": "RULE_NAME,
  "logConfig": {
    "enable": true,
    "metadata": LOGGING_METADATA
  }
}

Replace the placeholders with valid values:

  • PROJECT_ID: the ID of the project where the firewall rule is located.
  • RULE_NAME: the name of the firewall rule.
  • LOGGING_METADATA: whether Firewall Rules Logging includes metadata fields in firewall rule logs. You can configure this field only if logging is enabled. The value must be exclude-all or include-all. By default, metadata fields are included.

For more information, refer to the firewalls.patch method.

Disable Firewall Rules Logging

Console

  1. In the Google Cloud console, go to the Firewall policies page.

    Go to Firewall policies

  2. In the Logs column, determine if firewall logging is on or off for each firewall rule.

  3. To disable logging for one or more firewall rules, select the checkbox next to each rule that you want to update.

  4. In the VPC firewall rules action bar, click Configure logs.

  5. In the Configure logs dialog, select Off, and then click Save configuration.

gcloud 

gcloud compute firewall-rules update RULE_NAME \
    --no-enable-logging

Replace RULE_NAME with the name of the firewall rule.

API

Disable Firewall Rules Logging for an existing firewall rule.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/firewalls/RULE_NAME
{
  "name": "RULE_NAME,
  "logConfig": {
    "enable": false
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project where the firewall rule is located.
  • RULE_NAME: the name of the firewall rule.

For more information, refer to the firewalls.patch method.

View logs

Firewall rule logs are created in the project that hosts the network containing the VM instances and firewall rules. With Shared VPC, VM instances are created in service projects, but they use a Shared VPC Network located in the host project. Firewall rules logs are stored in that host project.

To view firewall rule logs, use the Logs Explorer section of the Google Cloud console.

The following queries demonstrate how you can search for specific firewall events.

View all firewall logs

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. Click Resource.

  3. In the Select resource list, click Subnetwork, and then click Apply.

  4. Click Log name, and then in the list, select firewall.

  5. Click Apply.

Alternatively:

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. Click Query.

  3. If you don't see the query editor field in the Query pane, click the Show query toggle.

  4. Paste the following into the query editor field on the Query pane. Replace PROJECT_ID with your project ID.

    resource.type="gce_subnetwork"
logName="projects/PROJECT_ID/logs/compute.googleapis.com%2Ffirewall"

  5. Click Run query.

View logs for specific subnets

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. Click Resource.

  3. In the Select resource list, click Subnetwork.

  4. Select the subnetwork that you want to view logs for, and then click Apply.

  5. Click Log name, and then in the list, select firewall.

  6. Click Apply.

Alternatively:

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. Click Query.

  3. If you don't see the query editor field in the Query pane, click the Show query toggle.

  4. Paste the following into the query editor field on the Query pane. Replace PROJECT_ID with your project ID and SUBNET_NAME with your subnetwork.

    resource.type="gce_subnetwork"
logName="projects/PROJECT_ID/logs/compute.googleapis.com%2Ffirewall"
resource.labels.subnetwork_name="SUBNET_NAME"

  5. Click Run query.

View logs in specific VMs

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. Click Resource.

  3. In the Select resource list, click VM instance.

  4. Select the instance that you want to view logs for, and then click Apply.

  5. Click Log name, and then in the list, select firewall.

  6. Click Apply.

Alternatively:

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. Click Query.

  3. If you don't see the query editor field in the Query pane, click the Show query toggle.

  4. Paste the following into the query editor field on the Query pane. Replace PROJECT_ID with your project ID and INSTANCE_ID with the ID of the VM that you want to view logs for.

    resource.type="gce_subnetwork"
logName="projects/PROJECT_ID/logs/compute.googleapis.com%2Ffirewall"
jsonPayload.instance.vm_name="INSTANCE_ID"

  5. Click Run query.

View logs for connections from a specific country

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. Click Query.

  3. If you don't see the query editor field in the Query pane, click the Show query toggle.

  4. Paste the following into the query editor field on the Query pane. Replace PROJECT_ID with your project ID and COUNTRY with the ISO 3166-1alpha-3 code.

    resource.type="gce_subnetwork"
logName="projects/PROJECT_ID/logs/compute.googleapis.com%2Ffirewall"
jsonPayload.remote_location.country=COUNTRY

Export logs

To export firewall rule logs, see Configure and manage sinks.

You can use the example queries to narrow the logs that you export.

Table of interactions

  • In the case of VM-to-VM communication, log records might be generated by both VMs, depending on their respective firewall rules.
  • The logged connection includes packets flowing both ways if the initial packet was allowed by the firewall.
  • For a given VM, incoming connections are matched against firewall rules configured on that VMs and outgoing connections are matched against egress firewall rule configured on that VM.
  • An allowed connection that matches a firewall rule with "allow and logging" is logged only once. The log entry is not repeated every 5 sec even if the connection endures.
  • A denied connection matching a firewall rule with "denied and logging" does repeat the log entry every 5 seconds for as long as there are packets observed in that denied connection.

This table shows the firewall logging behavior from the perspective of a single VM.

In a scenario in which a VM1 has an ingress rule R1 that matches packets and egress rule R2 that also matches packets, the behavior of firewall logging is as follows:

VM1 has Ingress Rule R1 (matching packets) VM1 has Egress Rule R2 (matching packets) Connection Direction Action Log
Allow + Log Allow Ingress Allow One log entry:
disposition=allow, rule=R1
Deny
Allow + Log
Deny + Log
Allow Allow Ingress Allow No logging
Deny
Allow + Log
Deny + Log
Deny + Log N/A Ingress Deny One log entry every 5 seconds:
disposition=deny, rule=R1
Deny N/A Ingress Deny No logging
Allow Allow + Log Egress Allow One log entry:
disposition=allow, rule=R2
Deny
Allow + Log
Deny + Log
Allow Allow Egress Allow No Logging
Deny
Allow + Log
Deny + Log
N/A Deny + Log Egress Deny One log entry every 5 seconds:
disposition=deny, rule=R2
N/A Deny Egress Deny No logging

Note that ingress and egress are symmetric.

This is the detailed description of the firewall logs semantics:

  • Allow + Log (logging is supported for TCP and UDP only)

    • Connection initiated in the direction to which the rule applies causes a single log record to be created.
    • Reply traffic is allowed due to connection tracking. Reply traffic does not cause any logging to occur, regardless of firewall rules in that direction.
    • If the connection expires from the firewall (inactive for 10 minutes or TCP RST received), then another packet in either direction may trigger logging.
    • Logging is based on 5-tuples. TCP flags do not affect logging behavior.

  • Deny + Log (logging is supported for TCP and UDP only)

    • Packets are dropped (no connection is initiated).
    • Each packet that corresponds to a unique 5-tuple is logged as a failed connection attempt.
    • The same 5-tuple is logged again every 5 seconds if it continues to receive packets.

Troubleshooting

Cannot view logs

If you cannot view firewall rule logs in the Logs Explorer section of the Google Cloud console, check the following:

Possible cause: Insufficient permissions

Ask the project owner to make sure your IAM principal at least has the Logs Viewer role for the project. Refer to permissions for more information.
Possible cause: Legacy networks not supported
You cannot use Firewall Rules Logging in a legacy network. Only VPC networks are supported.
Possible cause: Make sure you're looking in the correct project
Because firewall rule logs are stored with the project that contains the network, it's important to make sure you're looking for logs in the correct project. With Shared VPC, VM instances are created in service projects, but they use a Shared VPC network located in the host project. For Shared VPC scenarios, firewall rule logs are stored in that host project.

If Shared VPC is involved, you'll need appropriate permissions for the host project in order to view firewall rule logs. Even though the VM instances themselves are located in service projects, firewall rule logs for them are located in the host project.

Log entries missing

Possible cause: Connections might not match the firewall rule you expect

Verify that the firewall rule you expect is in the list of applicable firewall rules for an instance. Use the Google Cloud console to view details for the relevant instance, then click the View details button in the Network interfaces section on its VM instance details page. Inspect applicable firewall rules in the Firewall and routes details section of the VM's Network interface details page.

To make sure that you create your firewall rules correctly, review VPC firewall rules.

You can use tcpdump on the VM to determine if connections it sends or receives have addresses, ports, and protocols that would match the firewall you expect.

Possible cause: A higher priority rule with Firewall Rules Logging disabled might apply

Firewall rules are evaluated according to their priorities. From the perspective of a VM instance, only one firewall rule applies to the traffic.

A rule that you think would be the highest priority applicable rule might not actually be the highest priority applicable rule. A higher priority rule that does not have logging enabled might apply instead.

To troubleshoot, you can temporarily enable logging for all possible firewall rules applicable to a VM. Use the Google Cloud console to view details for the relevant VM, then click the View details button in the Network interfaces section on its VM instance details page. Inspect applicable firewall rules in the Firewall and routes details section of the VM's Network interface details page, and identify your custom rules in that list. Temporarily enable logging for all of those custom firewall rules.

With logging enabled, you can identify the applicable rule. Once identified, be sure to disable logging for all rules that do not actually need it.

Missing metadata for some log entries

Possible cause: Configuration propagation delay

If you update a firewall rule that has firewall logging enabled, it might take a few minutes before Google Cloud finishes propagating the changes necessary to log traffic that matches the rule's updated components.

What's next