vsx_provisioning_tool

R76 and Higher

Reference Guide

18 May 2014

Classification: [Protected]
© 2014 Check Point Software Technologies Ltd.
All rights reserved. This product and related documentation are protected by copyright and distributed under
licensing restricting their use, copying, distribution, and decompilation. No part of this product or related
documentation may be reproduced in any form or by any means without prior written authorization of Check
Point. While every precaution has been taken in the preparation of this book, Check Point assumes no
responsibility for errors or omissions. This publication and features described herein are subject to change
without notice.
RESTRICTED RIGHTS LEGEND:
Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR
52.227-19.
TRADEMARKS:
Refer to the Copyright page (http://www.checkpoint.com/copyright.html) for a list of our trademarks.
Refer to the Third Party copyright notices (http://www.checkpoint.com/3rd_party_copyright.html) for a list of
relevant copyrights and third-party licenses.
Important Information
Latest Software
We recommend that you install the most recent software release to stay up-to-date with the latest functional
improvements, stability fixes, security enhancements and protection against new and evolving attacks.

Latest Documentation
The latest version of this document is at:
(http://supportcontent.checkpoint.com/documentation_download?ID=33209)
To learn more, visit the Check Point Support Center (http://supportcenter.checkpoint.com).

Revision History
Date Description

18 May 2014 First release of this document

Feedback
Check Point is engaged in a continuous effort to improve its documentation.
Please help us by sending your comments
(mailto:cp_techpub_feedback@checkpoint.com?subject=Feedback on vsx_provisioning_tool R76 and
Higher Reference Guide).
 Contents

Important Information ............................................................................................................ 3

Introduction ............................................................................................................................ 5
Environment ........................................................................................................................ 5
Known Limitations ............................................................................................................... 5
Installation ........................................................................................................................... 6
Permissions ......................................................................................................................... 6
Command Line Syntax .......................................................................................................... 7
Transactions .......................................................................................................................... 8
vsx_provisioning_tool Commands ....................................................................................... 9
Transaction Explicit Commands .......................................................................................... 9
Adding a Virtual Device ....................................................................................................... 9
Deleting a Virtual Device ................................................................................................... 10
Changing Settings of a Virtual Device................................................................................ 10
Adding an Interface ........................................................................................................... 11
Removing an Interface ...................................................................................................... 12
Changing Settings of an Interface...................................................................................... 12
Adding a Route.................................................................................................................. 13
Removing a Route ............................................................................................................. 14
Showing Virtual Device Data ............................................................................................. 14
Script Examples ................................................................................................................... 14
 Introduction

Introduction
This document explains how to use the vsx_provisioning_tool command to add and remove virtual devices,
interfaces, and routes with CLI scripts.
Syntax notation:
Character Name Meaning

| Pipe OR

{} Curly brackets set of OR or AND

[] Square brackets optional

<> Angle Brackets variable

none required

Text in monospace: enter as shown here.

Text in italics: variable name. Enter your value.

Environment
R76 or higher management server on SecurePlatform, Gaia, Linux, or Windows:
 Security Management Server
 Multi-Domain Server
Managing:
 R75.40VS and higher VSX clusters
 R75.40VS and higher gateways
For VSX objects of lower versions (R68, R67, R65), only the show vd command is supported.
R76 or higher SmartConsole on Windows (optional).

Known Limitations
These features are not supported:
 Source Based Routes on Virtual Routers
 Layer-3 Monitoring IP on Virtual System in Bridge Mode working in Active-Standby Mode
 Unnumbered interfaces on a Virtual System leading to a Virtual Router
 Operations on the VSX object itself

vsx_provisioning_tool Reference Guide R76 and Higher | 5

 Introduction

Installation
Install this tool on Security Management Server, Multi-Domain Server, or SmartConsole computer, on Gaia,
SecurePlatform, Linux, or Windows. Get the vsx_provisioning_tool package from sk100645
(http://supportcontent.checkpoint.com/solutions?id=sk100645).
To install on Gaia, SecurePlatform, or Linux server:
1. Put the tool file in: $FWDIR/bin
2. Rename the file:
mv $FWDIR/bin/vsx_provisioning_tool.bin $FWDIR/bin/vsx_provisioning_tool
3. Give execution permissions: chmod +rx $FWDIR/bin/vsx_provisioning_tool
Note: In a Multi-Domain Security Management environment, put the tool on the Multi-Domain Server only.
The Domain Management Servers are linked to this path and get the tool from the Multi-Domain Server.
To install on Windows server:
Put the tool file in: %FWDIR%\bin\
To install on SmartConsole computer:
Put the tool file in the SmartConsole installation path. If you have multiple SmartConsole installations, put
the tool in the path for the version that matches the management server version:
 32-bit: C:\Program Files\CheckPoint\SmartConsole\<version>\PROGRAM\
 64-bit: C:\Program Files (x86)\CheckPoint\SmartConsole\<version>\PROGRAM\

Permissions
The vsx_provisioning_tool connects to the server in Write mode. Your username must have permissions to
execute VSX provisioning operations.
If you connect to the management server from a remote computer, define the IP address of the computer
running vsx_provisioning_tool as a GUI client.

Important - Do not connect with SmartDashboard in Write mode to the same Domain
Management Server while vsx_provisioning_tool runs. If you do, there can be issues and
unexpected results.

vsx_provisioning_tool Reference Guide R76 and Higher | 6

 Command Line Syntax

Command Line Syntax

Run the vsx_provisioning_tool on the Multi-Domain Server or Security Management Server.
vsx_provisioning_tool [-h]
Syntax vsx_provisioning_tool [-s <server>] {-u <user> | -c <certificate>}
-p <password> [-a] {-o <commands> | -f <inputFile> [-l <line>]}
Parameters

Parameter Description
-h
Show usage

-s IPv4 or IPv6 address, or DNS name, of the management server

(Required if vsx_provisioning_tool runs from a remote computer or Domain Management
Server)

-u Administrator user name

-c Path to administrator certificate file

-p Password of the user name or certificate file

-o Execute these commands ("vsx_provisioning_tool Commands" on page 9) on the

command line

-f Path to a file with the commands ("vsx_provisioning_tool Commands" on page 9) to run

-l Line number in file to start from

(Applied with -f flag)

-a Require connectivity to all VSX computers before committing transaction

Examples This line runs the commands from a text file:

vsx_provisioning_tool –s localhost -u admin -p admin -f
corpvsx.txt
This command creates a new Virtual System (VS1) on the VSX1 cluster and adds a VLAN
interface to VS1:
vsx_provisioning_tool –s localhost –u user –p pwd –o add vd name
VS1 vsx VSX1 , add interface name eth4.100 ip 1.1.1.1/24

Comments
 You must use the -o option or the -f option.
If you use a file: lines that begin with a hash sign (#) are treated as comments.
 If you use the -a flag, vsx_provisioning_tool makes sure it can connect to all VSX computers. But this
does not guarantee that all the VSX computers can successfully apply the changes.
 In Multi-Domain Security Management environments, the IP address of the server (-s option) must be
the Domain Management Server of the Virtual Device to change. If you run vsx_provisioning_tool locally
on a Multi-Domain Server, you can connect to the current Domain, as chosen by the mdsenv command.
Enter an IP address of localhost, or 127.0.0.1.

vsx_provisioning_tool Reference Guide R76 and Higher | 7

 Transactions

Exit Code

Return Code Description

0 Successfully applied all changes, on all cluster members.

1 Successfully applied all changes to the management database, but not to all VSX
members.

2 Successfully applied all changes, but SIC communication failed to establish with at least
one cluster member.

3 Connectivity check failed with at least one cluster member (if –a flag used). No changes
to the database or to the VSX machines applied.

4 Failed to apply changes (due to internal error, syntax error, or other).

If commands are executed from a file with multiple transactions, the exit code refers to the last transaction
processed.

Transactions
A transaction is a set of operations done on one Virtual Device. All operations are committed to the
database together when the transaction ends. If the transaction fails, all its commands are discarded.
Name the Virtual Device with a parameter in the first command (all commands have a parameter to name
the Virtual Device). You do not need to name it again in other commands of the same transaction. You
cannot send operations to different Virtual Devices in one transaction. You cannot start a new transaction
until you exit the one before.
When you send commands with the -o option, you can enter multiple commands (for example: add a Virtual
System and then add interfaces and routes to it). Separate the commands with a comma ( , ). All the
commands are one transaction. Explicit transaction commands are not allowed with this flag.
When you send commands with the -f option and a text file, you can use explicit transaction commands
("vsx_provisioning_tool Commands" on page 9). Commands from a file can be one or more transactions:
 If not inside a transaction, the current line is one transaction, which is automatically committed. You can
write multiple commands in one line (as one transaction), separated with a comma ( , ).
 If currently inside a transaction, the lines are processed, but no action is done until the transaction ends.
Important - If a transaction has more than 100 operations, it can have unexpected results.
Break the transaction to smaller transactions, or change the default timeouts
(http://supportcontent.checkpoint.com/solutions?id=sk98663).
Note - If both the management server and the Security Gateway are version R77.20, this is not an
issue.

vsx_provisioning_tool Reference Guide R76 and Higher | 8

 vsx_provisioning_tool Commands

vsx_provisioning_tool Commands
All vsx_provisioning_tool commands are pairs of key and value. The first two words in each command must
appear in the correct order. Other pairs can be given in any order.
You can write in-line comments with a hash ( # ). Everything after the hash is part of the comment.

Transaction Explicit Commands

Operation Command Syntax
transaction begin
Begin a new transaction
transaction end
End a transaction
transaction cancel
Cancel a transaction

Note - SIC with the Virtual System is established automatically. If it fails, operations continue and
the transaction returns error code 2.

Adding a Virtual Device

add vd name <vd name> vsx <vsx name> [type {vs|vsbm|vr|vsw}] [vs_mtu <MTU>]
[instances <IPv4 CoreXL instances>] [instances6 <IPv6 CoreXL instances>]
[main_ip <IPv4>] [main_ip6 <IPv6>] [calc_topo_auto {true|false}]
Parameter Value Notes
name Name of the Virtual Device Required if this is the first
command in a transaction

vsx VSX name to which the Virtual Device will be Required

added

type Type of Virtual Device: Default = vs

 vs – Virtual System
 vsbm – Virtual System in Bridge Mode
 vr – Virtual Router
 vsw – Virtual Switch
vs_mtu Global MTU value for all interfaces Applicable only for vsbm and
vsw
Default = 1500

instances Number of CoreXL instances for IPv4 Applicable only for vs and
vsbm
Default = 1

instances6 Number of CoreXL instances for IPv6 Applicable only for vs and
vsbm
Default = 1

main_ip Main IPv4 of the Virtual Device Applicable only for vs and vr

main_ip6 Main IPv6 of the Virtual Device Applicable only for vs and vr

calc_topo_auto If true (default), automatically calculates topology Applicable only for vs and vr
based on routes

vsx_provisioning_tool Reference Guide R76 and Higher | 9

 vsx_provisioning_tool Commands

Example:
vsx_provisioning_tool -s localhost -u user -p pwd -o add vd name VSW1 vsx VSX1
type vsw
Comments:
 If main_ip and main_ip6 are not used, the IPv4 and IPv6 addresses of the first interface added to
the new device become the main IP addresses.
 For a Virtual Switch, if you do not add a VLAN or physical interface in the same transaction, vs_mtu is
ignored.

Deleting a Virtual Device

remove vd name <vd name>
After you delete a Virtual Device, you cannot have more commands in the same transaction.
You cannot delete a Virtual Device if:
 It is referenced by a policy rule.
 It is referenced by other objects.
 It is enabled for global use in a Multi-Domain Security Management environment.

Changing Settings of a Virtual Device

set vd name <vd name> [vs_mtu <MTU>] [instances <IPv4 CoreXL instances>]
[instances6 <IPv6 CoreXL instances>] [main_ip <IPv4>] [main_ip6 <IPv6>]
[calc_topo_auto {true|false}]
Parameter Value Notes
name Name of the Virtual Device Required if this is the first
command in a transaction

vs_mtu Global MTU value for all interfaces Applicable only for vsbm and
vsw

instances Number of CoreXL instances for IPv4 Applicable only for vs and
vsbm

instances6 Number of CoreXL instances for IPv6 Applicable only for vs and
vsbm

main_ip Main IPv4 of the Virtual Device Applicable only for vs and vr

main_ip6 Main IPv6 of the Virtual Device Applicable only for vs and vr

calc_topo_auto To run automatic topology calculation based on Applicable only for vs and vr
routes

Example:
vsx_provisioning_tool –s localhost –u user –p pwd –o set vd name VS1 instances
8 main_ip 192.0.2.6 calc_topo_auto false
Comments:
 To remove existing values of main_ip and main_ip6, set the value to empty. For example: set vd
name VS1 main_ip6 empty

vsx_provisioning_tool Reference Guide R76 and Higher | 10

 vsx_provisioning_tool Commands

Adding an Interface
add interface vd <vd name> {name <interface>|leads_to <VR/VSW>} {ip|ip6
<address>{/<prefix length> | netmask <netmask> | netmask6 <netmask> | prefix
<IP prefix> | prefix6 <IP prefix> } [{propagate | propagate6 <true|false>]
[topology {external|internal_undefined|internal_this_network|internal_specific
specific_group <name>}] [mtu <MTU>]
Parameter Value Notes
vd Name of the Virtual Device Required if this is the first command in a
transaction

name Name of the physical or VLAN name or leads_to must be given, but not both
interface

leads_to Name of the Virtual Router or Applicable only for Virtual System
Virtual Switch that this interface is
connected to

ip | ip6 IPv4 or IPv6 of the interface Can be followed by a slash and a prefix length
parameter
Applicable only for Virtual System or Virtual
Router

netmask | If the address does not have a Use netmask6 or prefix6 for IPv6.
netmask6 slash-prefix length, you must
enter a netmask or a prefix Applicable only for Virtual System or Virtual
prefix | Router
prefix6
For interfaces on a Virtual System leading to a
Virtual Router, the netmask or prefix must be
the maximum possible for that address family:
 IPv4 – 32 (255.255.255.255)
 IPv6 – 128
propagate | If true, propagate the related IPv4 Applicable only for Virtual System and VLAN or
propagate6 or IPv6 route to adjacent Virtual physical interfaces
Devices
Default = false

topology Topology of the interface Applicable only for Virtual System, Virtual
Router, or Virtual System in Bridge Mode
Default for Virtual System, Virtual Router =
internal_this_network
Default for Virtual System in Bridge Mode =
internal_undefined
(internal_this_network cannot be set for
Virtual System in Bridge Mode)

specific_group If topology Applicable only if automatic topology calculation

internal_specific, name of is off
the group network object which
defines the topology

mtu MTU of the interface. Applicable only for Virtual System or Virtual
Router
Default = 1500

Example:
vsx_provisioning_tool –s localhost –u user –p pwd –o add interface vd VS1 name
eth4.100 ip 1.1.1.1/24

vsx_provisioning_tool Reference Guide R76 and Higher | 11

 vsx_provisioning_tool Commands

Removing an Interface
remove interface vd <vd name> {name <interface> | leads_to <VR/VSW>}
Parameter Value Notes
vd Name of the Virtual Device Required if this is the first command in a
transaction

name Name of the interface to remove name or leads_to must be given

You can give both, but if you do, they must be
consistent and identify the same interface

leads_to Name of the Virtual Router or Applicable only for Virtual System
Virtual Switch that this interface is
connected to

Example:
vsx_provisioning_tool –s localhost –u user –p pwd –o remove interface vd VS1
name eth4.100
Comments:
 If there are routes that have a next-hop IP which would become inaccessible without this interface, the
transaction will fail.
 IMPORTANT – If the interface being removed leads to a Virtual Router, all routes through that interface
will be removed automatically.

Changing Settings of an Interface

set interface vd <vd name> {name <interface> [new_name <interface>]|leads_to
<VR/VSW> [new_leads_to <VR/VSW>]} [{propagate|propagate6} {true|false}]
[topology {external|internal_undefined|internal_this_network|internal_specific
specific_group <name>}] [mtu <MTU>]
Parameter Value Notes
vd Name of the Virtual Device Required if this is the first command in a
transaction

name Name of the physical or VLAN name or leads_to must be given

interface to change if you give both, they must identify the same
interface

leads_to Name of the Virtual Router or Applicable only for Virtual System
Virtual Switch that this interface is
connected to

new_name New name for the interface You can change the name, but not the type of
interface:
new_leads_to New Virtual Router or Virtual  VLAN/physical interface can only be changed to a
Switch that this interface will VLAN/physical interface
connect to
 Interface leading to a VSW can only be changed
to lead to a different VSW.
 Interface leading to a VR can only be changed to
lead to a different VR.
propagate | If true, propagate the related IPv4 Applicable only for Virtual System, and for
propagate6 or IPv6 route to adjacent Virtual VLAN or physical interfaces
Devices

vsx_provisioning_tool Reference Guide R76 and Higher | 12

 vsx_provisioning_tool Commands

Parameter Value Notes

topology Topology of the interface Applicable only for Virtual System, Virtual
Router, or Virtual System in Bridge Mode
internal_this_network cannot be set for
Virtual System in Bridge Mode

If internal_specific, enter
specific_group with the name of the group
network object which defines the topology
(specific_group is applicable only if
automatic topology calculation is off)

mtu MTU of the interface. Applicable only for Virtual System or Virtual
Router

Example:
vsx_provisioning_tool –s localhost –u user –p pwd –o set interface vd VS1 name
eth4.100 new_name eth5 propagate true topology internal_specific specific_group
NYGWs
Comments:
You cannot change or remove the IP or netmask of an existing interface with this command. You can
remove the interface and add a new interface with a different IP, but not all the previous interface settings
will be kept.

Adding a Route
This command is applicable only for Virtual System and Virtual Router.
add route vd <vd name> destination {IP[/prefix] | default | default6} [{netmask
<netmask> | prefix <prefix length>}] {next_hop <next hop ip> | leads_to
<VR/VS>} [propagate {true|false}]
Parameter Value Notes
vd Name of the Virtual Device Required if this is the first command in a
transaction

destination IP address of the route IP version (IPv4 or IPv6) is automatically

destination, can have slash-prefix detected
length

netmask Netmask of the destination If an IP address (not default) is given without a

prefix, netmask or prefix must be given
prefix Prefix length of the destination

next_hop Next hop IP address for the route next_hop IP address must be on a subnet of
an existing interface
leads_to Name of the Virtual Router or
next_hop or leads_to must be given, but
Virtual System which will be the
next hop of the route not both

propagate If true, propagate this route to Applicable only if next_hop is given

adjacent Virtual Devices.
Default = false

Example:
vsx_provisioning_tool –s localhost –u user –p pwd –o add route vd VS1
destination default leads_to VR3

vsx_provisioning_tool Reference Guide R76 and Higher | 13

 Script Examples

Removing a Route
This command is applicable only for Virtual System and Virtual Router.
remove route vd <vd name> destination {IP[/prefix] | default | default6}
[{netmask <netmask> | prefix <prefix length>}]
Parameter Value Notes
vd Name of the Virtual Device Required if this is the first command in a
transaction

destination IP address of the route IP version (IPv4 or IPv6) is automatically

destination, can have slash-prefix detected
length

netmask Netmask of the destination If an IP address (not default) is given without a

prefix, netmask or prefix must be given
prefix Prefix length of the destination

Example:
vsx_provisioning_tool –s localhost –u user –p pwd –o remove route vd VS1
destination default6

Showing Virtual Device Data

show vd name <vd name>
Parameter Value Notes
vd Name of the Virtual Device Required

Comments:
 Only non-automatic routes are displayed. Routes which are automatically created with route propagation
are not displayed.
 For Virtual Router and Virtual Switch: automatically created wrpj interfaces which connect to a Virtual
System are not displayed.

Script Examples
Create a Virtual System connected to a Virtual Router, with a default route on the Virtual System to the
Virtual Router. Add routes on the Virtual Router going to the Virtual System.
transaction begin
add vd name VR1 vsx VSX1 type vr
add interface name eth3.100 ip 10.0.0.1/24
transaction end

transaction begin
add vd name VS1 vsx VSX1
add interface leads_to VR1 ip 192.168.1.1/32
add interface name eth4.20 ip 192.168.20.1/24 propagate true
add route destination default leads_to VR1
add route destination 192.168.40.0/25 next_hop 192.168.20.254
transaction end

transaction begin
add route vd VR1 destination 192.168.40.0/25 leads_to VS1
transaction end

vsx_provisioning_tool Reference Guide R76 and Higher | 14

 Script Examples

Create a Virtual System connected to a Virtual Switch, with manual topology.

transaction begin
add vd name VSW1 vsx VSX1 type vsw vs_mtu 1400
add interface name eth3.100
transaction end

transaction begin
add vd name VS1 vsx VSX1 calc_topo_auto false
add interface leads_to VSW1 ip 10.0.0.1/24 ip6 2001::1/64 topology external
add interface name eth4.20 ip 192.168.20.1/25 ip6 2020::1/64 topology
internal_this_network
add route destination default next_hop 10.0.0.254
add route destination default6 next_hop 2001::254
transaction end

Add CoreXL instances to the Virtual System made in the last example. Turn on automatic calculation of
topology. Change the name of the internal interface, and reduce its MTU.
transaction begin
set vd name VS1 instances 4 instances6 2 calc_topo_auto true
set interface name eth4.20 new_name eth4.21 mtu 1400
transaction end

vsx_provisioning_tool Reference Guide R76 and Higher | 15