diff options
23 files changed, 2362 insertions, 1482 deletions
diff --git a/docs/_static/css/code-snippets.css b/docs/_static/css/code-snippets.css index 0ae5464d..555b80d7 100644 --- a/docs/_static/css/code-snippets.css +++ b/docs/_static/css/code-snippets.css @@ -201,6 +201,10 @@ margin: 0 } +.rst-content div:has(ul + blockquote) blockquote { + margin: 15px 0 15px 24px +} + @media screen and (max-width: 991px) { .rst-content .linenodiv pre, .rst-content div[class^=highlight] pre, diff --git a/docs/_static/images/keypairs.png b/docs/_static/images/keypairs.png Binary files differnew file mode 100644 index 00000000..7e772ae9 --- /dev/null +++ b/docs/_static/images/keypairs.png diff --git a/docs/_static/images/lac-lns-diagram.jpg b/docs/_static/images/lac-lns-diagram.jpg Binary files differnew file mode 100644 index 00000000..4463a3c3 --- /dev/null +++ b/docs/_static/images/lac-lns-diagram.jpg diff --git a/docs/_static/images/lac-lns-winclient.jpg b/docs/_static/images/lac-lns-winclient.jpg Binary files differnew file mode 100644 index 00000000..9fa99152 --- /dev/null +++ b/docs/_static/images/lac-lns-winclient.jpg diff --git a/docs/_static/images/sg.png b/docs/_static/images/sg.png Binary files differnew file mode 100644 index 00000000..8be51e1f --- /dev/null +++ b/docs/_static/images/sg.png diff --git a/docs/_static/images/traffic.png b/docs/_static/images/traffic.png Binary files differnew file mode 100644 index 00000000..74002b16 --- /dev/null +++ b/docs/_static/images/traffic.png diff --git a/docs/automation/index.rst b/docs/automation/index.rst index ecabff7a..48e83a96 100644 --- a/docs/automation/index.rst +++ b/docs/automation/index.rst @@ -8,11 +8,11 @@ VyOS Automation .. toctree:: - :maxdepth: 1 + :maxdepth: 2 vyos-api vyos-ansible - vyos-terraform + terraform/index vyos-napalm vyos-netmiko vyos-salt diff --git a/docs/automation/terraform/index.rst b/docs/automation/terraform/index.rst new file mode 100644 index 00000000..9a51df91 --- /dev/null +++ b/docs/automation/terraform/index.rst @@ -0,0 +1,18 @@ +############## +VyOS Terraform +############## + + + * Nornir + * startup scripts + + +.. toctree:: + :maxdepth: 1 + :caption: Content + + terraformAWS +# terraformAZ +# terraformvSphere +# terraformGoogle + diff --git a/docs/automation/terraform/terraformAWS.rst b/docs/automation/terraform/terraformAWS.rst new file mode 100644 index 00000000..c81fe906 --- /dev/null +++ b/docs/automation/terraform/terraformAWS.rst @@ -0,0 +1,579 @@ +:lastproofread: 2024-01-11 + +.. _vyos-terraform: + +Terraform for VyOS +================== + +VyOS supports development infrastructure via Terraform and provisioning via Ansible. +Terraform allows you to automate the process of deploying instances on many cloud and virtual platforms. +In this article, we will look at using terraforms to deploy vyos on platforms - AWS, AZURE, and vSphere. +More detailed about what is Terraform you can write using the link_. + +Need to install_ Terraform + +Structure of files in the standard Terraform project: + +.. code-block:: none + + . + ├── main.tf # The main script + ├── version.tf # File for the changing version of Terraform. + ├── variables.tf # The file of all variables in "main.tf" + └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) + + +General commands that we will use for running Terraform scripts + + +.. code-block:: none + + #cd /<your folder> # go to the Terrafom project + #terraform init # install all addons and provider (aws az and so on) + #terraform plan # show wtah is changing + #terraform apply # run script + #yes # apply running + + +Deploying vyos in the AWS cloud +------------------------------- +With the help of terraforms, you can quickly deploy Vyos-based infrastructure in the AWS cloud. If necessary, the infrastructure can be removed using terraform. +Also we will make provisioning using Ansible. + + +.. image:: /_static/images/aws.png + :width: 50% + :align: center + :alt: Network Topology Diagram + +In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the AWS cloud and make provisioning using Ansible. + + +Preparation steps for deploying VyOS on AWS +------------------------------------------- + +How to create a single instance and install your configuration using Terraform+Ansible+AWS +Step by step: + +AWS + + +1.1 Create an account with AWS and get your "access_key", "secret key" + +1.2 Create a key pair_ and download your .pem key + +.. image:: /_static/images/keypairs.png + :width: 50% + :align: center + :alt: Network Topology Diagram + +1.3 Create a security group_ for the new VyOS instance and open all traffic + +.. image:: /_static/images/sg.png + :width: 50% + :align: center + :alt: Network Topology Diagram + + +.. image:: /_static/images/traffic.png + :width: 50% + :align: center + :alt: Network Topology Diagram + +Terraform + + +2.1 Create a0 UNIX or Windows instance + +2.2 Download and install Terraform + +2.3 Create the folder for example /root/awsterraform + +.. code-block:: none + + mkdir /root/awsterraform + +2.4 Copy all files into your Terraform project "/root/awsterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for AWS`_ + +2.5 Type the commands : + +.. code-block:: none + + #cd /<your folder> + #terraform init + + +Ansible + + +3.1 Create a UNIX instance whenever you want (local, cloud, and so on) + +3.2 Download and install Ansible + +3.3 Create the folder for example /root/aws/ + +3.4 Copy all files into your Ansible project "/root/aws/" (ansible.cfg, instance.yml, mykey.pem and "all"), more detailed see `Structure of files Ansible for AWS`_ + +mykey.pem you have to get using step 1.2 + + +Start + + +4.1 Type the commands on your Terrafom instance: + +.. code-block:: none + + #cd /<your folder> + #terraform plan + #terraform apply + #yes + + +Start creating an AWS instance and check the result +--------------------------------------------------- + +.. code-block:: none + + root@localhost:~/awsterraform# terraform apply + + Terraform used the selected providers to generate the following execution plan. + Resource actions are indicated with the following symbols: + + create + + Terraform will perform the following actions: + + # aws_instance.myVyOSec2 will be created + + resource "aws_instance" "myVyOSec2" { + + ami = "ami-************62c2d" + + arn = (known after apply) + + associate_public_ip_address = (known after apply) + + availability_zone = (known after apply) + + cpu_core_count = (known after apply) + + cpu_threads_per_core = (known after apply) + + disable_api_stop = (known after apply) + + disable_api_termination = (known after apply) + + ebs_optimized = (known after apply) + + get_password_data = false + + host_id = (known after apply) + + host_resource_group_arn = (known after apply) + + iam_instance_profile = (known after apply) + + id = (known after apply) + + instance_initiated_shutdown_behavior = (known after apply) + + instance_lifecycle = (known after apply) + + instance_state = (known after apply) + + instance_type = "t2.micro" + + ipv6_address_count = (known after apply) + + ipv6_addresses = (known after apply) + + key_name = "awsterraform" + + monitoring = (known after apply) + + outpost_arn = (known after apply) + + password_data = (known after apply) + + placement_group = (known after apply) + + placement_partition_number = (known after apply) + + primary_network_interface_id = (known after apply) + + private_dns = (known after apply) + + private_ip = (known after apply) + + public_dns = (known after apply) + + public_ip = (known after apply) + + secondary_private_ips = (known after apply) + + security_groups = [ + + "awsterraformsg", + ] + + source_dest_check = true + + spot_instance_request_id = (known after apply) + + subnet_id = (known after apply) + + tags = { + + "name" = "VyOS System" + } + + tags_all = { + + "name" = "VyOS System" + } + + tenancy = (known after apply) + + user_data = (known after apply) + + user_data_base64 = (known after apply) + + user_data_replace_on_change = false + + vpc_security_group_ids = (known after apply) + } + + # local_file.ip will be created + + resource "local_file" "ip" { + + content = (known after apply) + + content_base64sha256 = (known after apply) + + content_base64sha512 = (known after apply) + + content_md5 = (known after apply) + + content_sha1 = (known after apply) + + content_sha256 = (known after apply) + + content_sha512 = (known after apply) + + directory_permission = "0777" + + file_permission = "0777" + + filename = "ip.txt" + + id = (known after apply) + } + + # null_resource.SSHconnection1 will be created + + resource "null_resource" "SSHconnection1" { + + id = (known after apply) + } + + # null_resource.SSHconnection2 will be created + + resource "null_resource" "SSHconnection2" { + + id = (known after apply) + } + + Plan: 4 to add, 0 to change, 0 to destroy. + + Changes to Outputs: + + my_IP = (known after apply) + + Do you want to perform these actions? + Terraform will perform the actions described above. + Only 'yes' will be accepted to approve. + + Enter a value: yes + + aws_instance.myVyOSec2: Creating... + aws_instance.myVyOSec2: Still creating... [10s elapsed] + aws_instance.myVyOSec2: Still creating... [20s elapsed] + aws_instance.myVyOSec2: Still creating... [30s elapsed] + aws_instance.myVyOSec2: Still creating... [40s elapsed] + aws_instance.myVyOSec2: Creation complete after 44s [id=i-09edfca15aac2fe0a] + null_resource.SSHconnection1: Creating... + null_resource.SSHconnection2: Creating... + null_resource.SSHconnection1: Provisioning with 'file'... + null_resource.SSHconnection2: Provisioning with 'remote-exec'... + null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH... + null_resource.SSHconnection2 (remote-exec): Host: 10.217.80.104 + null_resource.SSHconnection2 (remote-exec): User: root + null_resource.SSHconnection2 (remote-exec): Password: true + null_resource.SSHconnection2 (remote-exec): Private key: false + null_resource.SSHconnection2 (remote-exec): Certificate: false + null_resource.SSHconnection2 (remote-exec): SSH Agent: false + null_resource.SSHconnection2 (remote-exec): Checking Host Key: false + null_resource.SSHconnection2 (remote-exec): Target Platform: unix + local_file.ip: Creating... + local_file.ip: Creation complete after 0s [id=e8e91f2e24579cd28b92e2d152c0c24c3bf4b52c] + null_resource.SSHconnection2 (remote-exec): Connected! + null_resource.SSHconnection1: Creation complete after 0s [id=7070868940858935600] + + null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************ + + null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] ************** + null_resource.SSHconnection2: Still creating... [10s elapsed] + null_resource.SSHconnection2: Still creating... [20s elapsed] + null_resource.SSHconnection2: Still creating... [30s elapsed] + null_resource.SSHconnection2: Still creating... [40s elapsed] + null_resource.SSHconnection2: Still creating... [50s elapsed] + null_resource.SSHconnection2: Still creating... [1m0s elapsed] + null_resource.SSHconnection2 (remote-exec): ok: [54.144.84.120] + + null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* + null_resource.SSHconnection2: Still creating... [1m10s elapsed] + null_resource.SSHconnection2 (remote-exec): changed: [54.144.84.120] + + null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* + null_resource.SSHconnection2 (remote-exec): 54.144.84.120 : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + + null_resource.SSHconnection2: Creation complete after 1m16s [id=4902256962410024771] + + Apply complete! Resources: 4 added, 0 changed, 0 destroyed. + + Outputs: + + my_IP = "54.144.84.120" + + + +After executing all the commands you will have your VyOS instance on the AWS cloud with your configuration, it's a very convenient desition. +If you need to delete the instance please type the command: + +.. code-block:: none + + #terraform destroy + + +Troubleshooting +--------------- + +1. Ansible doesn't connect via SSH to your AWS instance: you have to check that your SSH key has copied into the path /root/aws/. +Also, increase the time in the file instance.yml from 300 sec to 500 sec or more. (It depends on your location). +Make sure that you have opened access to the instance in the security group. + +2. Terraform doesn't connect via SSH to your Ansible instance: you have to check the correct login and password in the part of the file vyos. tf + +.. code-block:: none + + connection { + type = "ssh" + user = "root" # open root access using login and password on your Ansible + password = var.password # check password in the file terraform.tfvars isn't empty + host = var.host # check the correct IP address of your Ansible host + } + + +Make sure that Ansible is pinging from Terrafom. + +Structure of files Terrafom for AWS +----------------------------------- + +.. code-block:: none + + . + ├── vyos.tf # The main script + ├── var.tf # File for the changing version of Terraform. + ├── versions.tf # The file of all variables in "vyos.tf" + └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) + + + +File contents of Terrafom for AWS +--------------------------------- + +vyos.tf + +.. code-block:: none + + + ############################################################################## + # Build an VyOS VM from the Marketplace + # To finde nessesery AMI image_ in AWS + # + # In the script vyos.tf we'll use default values (you can chang it as you need) + # AWS Region = "us-east-1" + # AMI = "standard AMI of VyOS from AWS Marketplace" + # Size of VM = "t2.micro" + # AWS Region = "us-east-1" + # After deploying the AWS instance and getting an IP address, the IP address is copied into the file + #"ip.txt" and copied to the Ansible node for provisioning. + ############################################################################## + + provider "aws" { + access_key = var.access + secret_key = var.secret + region = var.region + } + + variable "region" { + default = "us-east-1" + description = "AWS Region" + } + + variable "ami" { + default = "ami-**************3b3" # ami image please enter your details + description = "Amazon Machine Image ID for VyOS" + } + + variable "type" { + default = "t2.micro" + description = "Size of VM" + } + + # my resource for VyOS + + resource "aws_instance" "myVyOSec2" { + ami = var.ami + key_name = "awsterraform" # Please enter your details from 1.2 of Preparation steps for deploying VyOS on AWS + security_groups = ["awsterraformsg"] # Please enter your details from 1.3 of Preparation steps for deploying VyOS on AWS + instance_type = var.type + tags = { + name = "VyOS System" + } + } + + ############################################################################## + # specific variable (to getting type "terraform plan"): + # aws_instance.myVyOSec2.public_ip - the information about public IP address + # of our instance, needs for provisioning and ssh connection from Ansible + ############################################################################## + + output "my_IP"{ + value = aws_instance.myVyOSec2.public_ip + } + + ############################################################################## + # + # IP of aws instance copied to a file ip.txt in local system Terraform + # ip.txt looks like: + # cat ./ip.txt + # ххх.ххх.ххх.ххх + ############################################################################## + + resource "local_file" "ip" { + content = aws_instance.myVyOSec2.public_ip + filename = "ip.txt" + } + + #connecting to the Ansible control node using SSH connection + + ############################################################################## + # Steps "SSHconnection1" and "SSHconnection2" need to get file ip.txt from the terraform node and start remotely the playbook of Ansible. + ############################################################################## + + resource "null_resource" "SSHconnection1" { + depends_on = [aws_instance.myVyOSec2] + connection { + type = "ssh" + user = "root" + password = var.password + host = var.host + } + + #copying the ip.txt file to the Ansible control node from local system + + provisioner "file" { + source = "ip.txt" + destination = "/root/aws/ip.txt" # The folder of your Ansible project + } + } + + resource "null_resource" "SSHconnection2" { + depends_on = [aws_instance.myVyOSec2] + connection { + type = "ssh" + user = "root" + password = var.password + host = var.host + } + #command to run Ansible playbook on remote Linux OS + provisioner "remote-exec" { + inline = [ + "cd /root/aws/", + "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for AWS" + ] + } + } + + +var.tf + +.. code-block:: none + + variable "password" { + description = "pass for Ansible" + type = string + sensitive = true + } + variable "host"{ + description = "The IP of my Ansible" + type = string + } + variable "access" { + description = "my access_key for AWS" + type = string + sensitive = true + } + variable "secret" { + description = "my secret_key for AWS" + type = string + sensitive = true + } + +versions.tf + +.. code-block:: none + + terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 5.0" + } + } + } + +terraform.tfvars + +.. code-block:: none + + password = "" # password for Ansible SSH + host = "" # IP of my Ansible + access = "" # access_key for AWS + secret = "" # secret_key for AWS + + +Structure of files Ansible for AWS +---------------------------------- + +.. code-block:: none + + . + ├── group_vars + └── all + ├── ansible.cfg + ├── mykey.pem + └── instance.yml + + +File contents of Ansible for AWS +-------------------------------- + +ansible.cfg + +.. code-block:: none + + [defaults] + inventory = /root/aws/ip.txt + host_key_checking= False + private_key_file = /root/aws/awsterraform.pem # check the name + remote_user=vyos + +mykey.pem + +.. code-block:: none + + Copy your key.pem from AWS + + +instance.yml + + + +.. code-block:: none + + ############################################################################## + # About tasks: + # "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds + # "Configure general settings for the vyos hosts group" - make provisioning into AWS VyOS node + # You have to add all necessary cammans of VyOS under the block "lines:" + ############################################################################## + + + - name: integration of terraform and ansible + hosts: all + gather_facts: 'no' + + tasks: + + - name: "Wait 300 seconds, but only start checking after 60 seconds" + wait_for_connection: + delay: 60 + timeout: 300 + + - name: "Configure general settings for the vyos hosts group" + vyos_config: + lines: + - set system name-server 8.8.8.8 + save: + true + + +all + +.. code-block:: none + + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos + ansible_user: vyos + +Sourse files for AWS from GIT +----------------------------- + +All files about the article can be found here_ + + +.. _link: https://developer.hashicorp.com/terraform/intro +.. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli +.. _pair: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html +.. _group: https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html +.. _image: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html +.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main
\ No newline at end of file diff --git a/docs/automation/vyos-terraform.rst b/docs/automation/vyos-terraform.rst deleted file mode 100644 index 75967202..00000000 --- a/docs/automation/vyos-terraform.rst +++ /dev/null @@ -1,1036 +0,0 @@ -:lastproofread: 2024-01-11 - -.. _vyos-terraform: - -Terraform -========= - -VyOS supports develop infrastructia via Terraform and provisioning via ansible. -Need to install ``Terraform`` - -Structure of files - -.. code-block:: none - - . - ├── main.tf - ├── version.tf - ├── variables.tf - └── terraform.tfvars - -Run Terraform -------------- - -.. code-block:: none - - #cd /your folder - #terraform init - #terraform plan - #terraform apply - #yes - - -Deploying vyos in the AWS cloud -------------------------------- -With the help of terraforms, you can quickly deploy Vyos-based infrastructure in the AWS cloud. If necessary, the infrastructure can be removed using terraform. -Also we will make provisioning using Ansible. - -Structure of files Terrafom - -.. code-block:: none - - . - ├── vyos.tf - └── var.tf - -File contents -------------- - -vyos.tf - -.. code-block:: none - - terraform { - required_providers { - aws = { - source = "hashicorp/aws" - version = "~> 5.0" - } - } - } - - provider "aws" { - access_key = var.access - secret_key = var.secret - region = var.region - } - - variable "region" { - default = "us-east-1" - description = "AWS Region" - } - - variable "ami" { - default = "ami-**************" # ami image please enter your details - description = "Amazon Machine Image ID for VyOS" - } - - variable "type" { - default = "t2.micro" - description = "Size of VM" - } - - # my resource for VyOS - - resource "aws_instance" "myVyOSec2" { - ami = var.ami - key_name = "mykeyname" # Please enter your details - security_groups = ["my_sg"] # Please enter your details - instance_type = var.type - tags = { - name = "VyOS System" - } - } - - output "my_IP"{ - value = aws_instance.myVyOSec2.public_ip - } - - - #IP of aws instance copied to a file ip.txt in local system Terraform - - resource "local_file" "ip" { - content = aws_instance.myVyOSec2.public_ip - filename = "ip.txt" - } - - #connecting to the Ansible control node using SSH connection - - resource "null_resource" "SSHconnection1" { - depends_on = [aws_instance.myVyOSec2] - connection { - type = "ssh" - user = "root" - password = var.password - host = var.host - } - #copying the ip.txt file to the Ansible control node from local system - provisioner "file" { - source = "ip.txt" - destination = "/root/aws/ip.txt" # The folder of your Ansible project - } - } - - resource "null_resource" "SSHconnection2" { - depends_on = [aws_instance.myVyOSec2] - connection { - type = "ssh" - user = "root" - password = var.password - host = var.host - } - #command to run Ansible playbook on remote Linux OS - provisioner "remote-exec" { - inline = [ - "cd /root/aws/", - "ansible-playbook instance.yml" - ] - } - } - - -var.tf - -.. code-block:: none - - variable "password" { - description = "pass for Ansible" - type = string - sensitive = true - } - variable "host"{ - description = "The IP of my Ansible" - } - variable "access" { - description = "my access_key for AWS" - type = string - sensitive = true - } - variable "secret" { - description = "my secret_key for AWS" - type = string - sensitive = true - } - - -Structure of files Ansible - -.. code-block:: none - - . - ├── group_vars - └── all - ├── ansible.cfg - ├── mykey.pem - └── instance.yml - - -File contents -------------- - -ansible.cfg - -.. code-block:: none - - [defaults] - inventory = /root/aws/ip.txt - host_key_checking= False - private_key_file = /root/aws/mykey.pem - remote_user=vyos - -mykey.pem - -.. code-block:: none - - -----BEGIN OPENSSH PRIVATE KEY----- - - Copy your key.pem from AWS - - -----END OPENSSH PRIVATE KEY----- - -instance.yml - -.. code-block:: none - - - name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the vyos hosts group" - vyos_config: - lines: - - set system name-server 8.8.8.8 - save: - true - - -all - -.. code-block:: none - - ansible_connection: ansible.netcommon.network_cli - ansible_network_os: vyos.vyos.vyos - ansible_user: vyos - -AWS_terraform_ansible_single_vyos_instance ------------------------------------------- - -How to create a single instance and install your configuration using Terraform+Ansible+AWS -Step by step: - -AWS ---- - -1.1 Create an account with AWS and get your "access_key", "secret key" - -1.2 Create a key pair and download your .pem key - -1.3 Create a security group for the new VyOS instance - -Terraform ---------- - -2.1 Create a UNIX or Windows instance - -2.2 Download and install Terraform - -2.3 Create the folder for example ../awsvyos/ - -2.4 Copy all files into your Terraform project (vyos.tf, var.tf) -2.4.1 Please type the information into the strings 22, 35, 36 of file "vyos.tf" - -2.5 Type the commands : - - #cd /your folder - - #terraform init - -Ansible -------- - -3.1 Create a UNIX instance - -3.2 Download and install Ansible - -3.3 Create the folder for example /root/aws/ - -3.4 Copy all files from my folder /Ansible into your Ansible project (ansible.cfg, instance.yml, mykey.pem) - -mykey.pem you have to get using step 1.2 - -Start ------ - -4.1 Type the commands on your Terrafom instance: - - #cd /your folder - - #terraform plan - - #terraform apply - - #yes - -.. image:: /_static/images/aws.png - :width: 80% - :align: center - :alt: Network Topology Diagram - - - -Deploying vyos in the Azure cloud ---------------------------------- -With the help of terraforms, you can quickly deploy Vyos-based infrastructure in the Azure cloud. If necessary, the infrastructure can be removed using terraform. - -Structure of files Terrafom - -.. code-block:: none - - . - ├── main.tf - └── variables.tf - -File contents -------------- - -main.tf - -.. code-block:: none - - ############################################################################## - # HashiCorp Guide to Using Terraform on Azure - # This Terraform configuration will create the following: - # Resource group with a virtual network and subnet - # An VyOS server without ssh key (only login+password) - ############################################################################## - - # Chouse a provider - - provider "azurerm" { - features {} - } - - # Create a resource group. In Azure every resource belongs to a - # resource group. - - resource "azurerm_resource_group" "azure_vyos" { - name = "${var.resource_group}" - location = "${var.location}" - } - - # The next resource is a Virtual Network. - - resource "azurerm_virtual_network" "vnet" { - name = "${var.virtual_network_name}" - location = "${var.location}" - address_space = ["${var.address_space}"] - resource_group_name = "${var.resource_group}" - } - - # Build a subnet to run our VMs in. - - resource "azurerm_subnet" "subnet" { - name = "${var.prefix}subnet" - virtual_network_name = "${azurerm_virtual_network.vnet.name}" - resource_group_name = "${var.resource_group}" - address_prefixes = ["${var.subnet_prefix}"] - } - - ############################################################################## - # Build an VyOS VM from the Marketplace - # To finde nessesery image use the command: - # - # az vm image list --offer vyos --all - # - # Now that we have a network, we'll deploy an VyOS server. - # An Azure Virtual Machine has several components. In this example we'll build - # a security group, a network interface, a public ip address, a storage - # account and finally the VM itself. Terraform handles all the dependencies - # automatically, and each resource is named with user-defined variables. - ############################################################################## - - - # Security group to allow inbound access on port 22 (ssh) - - resource "azurerm_network_security_group" "vyos-sg" { - name = "${var.prefix}-sg" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - - security_rule { - name = "SSH" - priority = 100 - direction = "Inbound" - access = "Allow" - protocol = "Tcp" - source_port_range = "*" - destination_port_range = "22" - source_address_prefix = "${var.source_network}" - destination_address_prefix = "*" - } - } - - # A network interface. - - resource "azurerm_network_interface" "vyos-nic" { - name = "${var.prefix}vyos-nic" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - - ip_configuration { - name = "${var.prefix}ipconfig" - subnet_id = "${azurerm_subnet.subnet.id}" - private_ip_address_allocation = "Dynamic" - public_ip_address_id = "${azurerm_public_ip.vyos-pip.id}" - } - } - - # Add a public IP address. - - resource "azurerm_public_ip" "vyos-pip" { - name = "${var.prefix}-ip" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - allocation_method = "Dynamic" - } - - # Build a virtual machine. This is a standard VyOS instance from Marketplace. - - resource "azurerm_virtual_machine" "vyos" { - name = "${var.hostname}-vyos" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - vm_size = "${var.vm_size}" - - network_interface_ids = ["${azurerm_network_interface.vyos-nic.id}"] - delete_os_disk_on_termination = "true" - - # To finde an information about the plan use the command: - # az vm image list --offer vyos --all - - plan { - publisher = "sentriumsl" - name = "vyos-1-3" - product = "vyos-1-2-lts-on-azure" - } - - storage_image_reference { - publisher = "${var.image_publisher}" - offer = "${var.image_offer}" - sku = "${var.image_sku}" - version = "${var.image_version}" - } - - storage_os_disk { - name = "${var.hostname}-osdisk" - managed_disk_type = "Standard_LRS" - caching = "ReadWrite" - create_option = "FromImage" - } - - os_profile { - computer_name = "${var.hostname}" - admin_username = "${var.admin_username}" - admin_password = "${var.admin_password}" - } - - os_profile_linux_config { - disable_password_authentication = false - } - } - - data "azurerm_public_ip" "example" { - depends_on = ["azurerm_virtual_machine.vyos"] - name = "vyos-ip" - resource_group_name = "${var.resource_group}" - } - output "public_ip_address" { - value = data.azurerm_public_ip.example.ip_address - } - - # IP of AZ instance copied to a file ip.txt in local system - - resource "local_file" "ip" { - content = data.azurerm_public_ip.example.ip_address - filename = "ip.txt" - } - - #Connecting to the Ansible control node using SSH connection - - resource "null_resource" "nullremote1" { - depends_on = ["azurerm_virtual_machine.vyos"] - connection { - type = "ssh" - user = "root" - password = var.password - host = var.host - } - - # Copying the ip.txt file to the Ansible control node from local system - - provisioner "file" { - source = "ip.txt" - destination = "/root/az/ip.txt" - } - } - - resource "null_resource" "nullremote2" { - depends_on = ["azurerm_virtual_machine.vyos"] - connection { - type = "ssh" - user = "root" - password = var.password - host = var.host - } - - # Command to run ansible playbook on remote Linux OS - - provisioner "remote-exec" { - - inline = [ - "cd /root/az/", - "ansible-playbook instance.yml" - ] - } - } - - - -variables.tf - -.. code-block:: none - - ############################################################################## - # Variables File - # - # Here is where we store the default values for all the variables used in our - # Terraform code. - ############################################################################## - - variable "resource_group" { - description = "The name of your Azure Resource Group." - default = "my_resource_group" - } - - variable "prefix" { - description = "This prefix will be included in the name of some resources." - default = "vyos" - } - - variable "hostname" { - description = "Virtual machine hostname. Used for local hostname, DNS, and storage-related names." - default = "vyos_terraform" - } - - variable "location" { - description = "The region where the virtual network is created." - default = "centralus" - } - - variable "virtual_network_name" { - description = "The name for your virtual network." - default = "vnet" - } - - variable "address_space" { - description = "The address space that is used by the virtual network. You can supply more than one address space. Changing this forces a new resource to be created." - default = "10.0.0.0/16" - } - - variable "subnet_prefix" { - description = "The address prefix to use for the subnet." - default = "10.0.10.0/24" - } - - variable "storage_account_tier" { - description = "Defines the storage tier. Valid options are Standard and Premium." - default = "Standard" - } - - variable "storage_replication_type" { - description = "Defines the replication type to use for this storage account. Valid options include LRS, GRS etc." - default = "LRS" - } - - # The most chippers size - - variable "vm_size" { - description = "Specifies the size of the virtual machine." - default = "Standard_B1s" - } - - variable "image_publisher" { - description = "Name of the publisher of the image (az vm image list)" - default = "sentriumsl" - } - - variable "image_offer" { - description = "Name of the offer (az vm image list)" - default = "vyos-1-2-lts-on-azure" - } - - variable "image_sku" { - description = "Image SKU to apply (az vm image list)" - default = "vyos-1-3" - } - - variable "image_version" { - description = "Version of the image to apply (az vm image list)" - default = "1.3.3" - } - - variable "admin_username" { - description = "Administrator user name" - default = "vyos" - } - - variable "admin_password" { - description = "Administrator password" - default = "Vyos0!" - } - - variable "source_network" { - description = "Allow access from this network prefix. Defaults to '*'." - default = "*" - } - - variable "password" { - description = "pass for Ansible" - type = string - sensitive = true - } - variable "host"{ - description = "IP of my Ansible" - } - - -Structure of files Ansible - -.. code-block:: none - - . - ├── group_vars - └── all - ├── ansible.cfg - └── instance.yml - - -File contents -------------- - -ansible.cfg - -.. code-block:: none - - [defaults] - inventory = /root/az/ip.txt - host_key_checking= False - remote_user=vyos - - -instance.yml - -.. code-block:: none - - - name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the vyos hosts group" - vyos_config: - lines: - - set system name-server 8.8.8.8 - save: - true - - -all - -.. code-block:: none - - ansible_connection: ansible.netcommon.network_cli - ansible_network_os: vyos.vyos.vyos - - # user and password gets from terraform variables "admin_username" and "admin_password" - ansible_user: vyos - ansible_ssh_pass: Vyos0! - - -Azure_terraform_ansible_single_vyos_instance --------------------------------------------- - -How to create a single instance and install your configuration using Terraform+Ansible+Azure -Step by step: - -Azure ------ - -1.1 Create an account with Azure - -Terraform ---------- - -2.1 Create a UNIX or Windows instance - -2.2 Download and install Terraform - -2.3 Create the folder for example ../azvyos/ - -2.4 Copy all files from my folder /Terraform into your Terraform project (main.tf, variables.tf) - -2.5 Login with Azure using the command - - #az login - -2.6 Type the commands : - - #cd /your folder - - #terraform init - -Ansible -------- - -3.1 Create a UNIX instance - -3.2 Download and install Ansible - -3.3 Create the folder for example /root/az/ - -3.4 Copy all files from my folder /Ansible into your Ansible project (ansible.cfg, instance.yml and /group_vars) - -Start ------ - -4.1 Type the commands on your Terrafom instance: - - #cd /your folder - - #terraform plan - - #terraform apply - - #yes - - - -Deploying vyos in the Vsphere infrastructia -------------------------------------------- -With the help of terraforms, you can quickly deploy Vyos-based infrastructure in the vSphere. - -Structure of files Terrafom - -.. code-block:: none - - . - ├── main.tf - ├── versions.tf - ├── variables.tf - └── terraform.tfvars - -File contents -------------- - -main.tf - -.. code-block:: none - - provider "vsphere" { - user = var.vsphere_user - password = var.vsphere_password - vsphere_server = var.vsphere_server - allow_unverified_ssl = true - } - - data "vsphere_datacenter" "datacenter" { - name = var.datacenter - } - - data "vsphere_datastore" "datastore" { - name = var.datastore - datacenter_id = data.vsphere_datacenter.datacenter.id - } - - data "vsphere_compute_cluster" "cluster" { - name = var.cluster - datacenter_id = data.vsphere_datacenter.datacenter.id - } - - data "vsphere_resource_pool" "default" { - name = format("%s%s", data.vsphere_compute_cluster.cluster.name, "/Resources/terraform") # set as you need - datacenter_id = data.vsphere_datacenter.datacenter.id - } - - data "vsphere_host" "host" { - name = var.host - datacenter_id = data.vsphere_datacenter.datacenter.id - } - - data "vsphere_network" "network" { - name = var.network_name - datacenter_id = data.vsphere_datacenter.datacenter.id - } - - ## Deployment of VM from Remote OVF - resource "vsphere_virtual_machine" "vmFromRemoteOvf" { - name = var.remotename - datacenter_id = data.vsphere_datacenter.datacenter.id - datastore_id = data.vsphere_datastore.datastore.id - host_system_id = data.vsphere_host.host.id - resource_pool_id = data.vsphere_resource_pool.default.id - network_interface { - network_id = data.vsphere_network.network.id - } - wait_for_guest_net_timeout = 2 - wait_for_guest_ip_timeout = 2 - - ovf_deploy { - allow_unverified_ssl_cert = true - remote_ovf_url = var.url_ova - disk_provisioning = "thin" - ip_protocol = "IPv4" - ip_allocation_policy = "dhcpPolicy" - ovf_network_map = { - "Network 1" = data.vsphere_network.network.id - "Network 2" = data.vsphere_network.network.id - } - } - vapp { - properties = { - "password" = "12345678", - "local-hostname" = "terraform_vyos" - } - } - } - - output "ip" { - description = "default ip address of the deployed VM" - value = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address - } - - # IP of AZ instance copied to a file ip.txt in local system - - resource "local_file" "ip" { - content = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address - filename = "ip.txt" - } - - #Connecting to the Ansible control node using SSH connection - - resource "null_resource" "nullremote1" { - depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] - connection { - type = "ssh" - user = "root" - password = var.ansiblepassword - host = var.ansiblehost - - } - - # Copying the ip.txt file to the Ansible control node from local system - - provisioner "file" { - source = "ip.txt" - destination = "/root/vsphere/ip.txt" - } - } - - resource "null_resource" "nullremote2" { - depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] - connection { - type = "ssh" - user = "root" - password = var.ansiblepassword - host = var.ansiblehost - } - - # Command to run ansible playbook on remote Linux OS - - provisioner "remote-exec" { - - inline = [ - "cd /root/vsphere/", - "ansible-playbook instance.yml" - ] - } - } - - -versions.tf - -.. code-block:: none - - # Copyright (c) HashiCorp, Inc. - # SPDX-License-Identifier: MPL-2.0 - - terraform { - required_providers { - vsphere = { - source = "hashicorp/vsphere" - version = "2.4.0" - } - } - } - -variables.tf - -.. code-block:: none - - # Copyright (c) HashiCorp, Inc. - # SPDX-License-Identifier: MPL-2.0 - - variable "vsphere_server" { - description = "vSphere server" - type = string - } - - variable "vsphere_user" { - description = "vSphere username" - type = string - } - - variable "vsphere_password" { - description = "vSphere password" - type = string - sensitive = true - } - - variable "datacenter" { - description = "vSphere data center" - type = string - } - - variable "cluster" { - description = "vSphere cluster" - type = string - } - - variable "datastore" { - description = "vSphere datastore" - type = string - } - - variable "network_name" { - description = "vSphere network name" - type = string - } - - variable "host" { - description = "name if yor host" - type = string - } - - variable "remotename" { - description = "the name of you VM" - type = string - } - - variable "url_ova" { - description = "the URL to .OVA file or cloude store" - type = string - } - - variable "ansiblepassword" { - description = "Ansible password" - type = string - } - - variable "ansiblehost" { - description = "Ansible host name or IP" - type = string - } - -terraform.tfvars - -.. code-block:: none - - vsphere_user = "" - vsphere_password = "" - vsphere_server = "" - datacenter = "" - datastore = "" - cluster = "" - network_name = "" - host = "" - url_ova = "" - ansiblepassword = "" - ansiblehost = "" - remotename = "" - -Azure_terraform_ansible_single_vyos_instance --------------------------------------------- - -How to create a single instance and install your configuration using Terraform+Ansible+Vsphere -Step by step: - -Vsphere -------- - -1.1 Collect all data in to file "terraform.tfvars" and create resources fo example "terraform" - -Terraform ---------- - -2.1 Create a UNIX or Windows instance - -2.2 Download and install Terraform - -2.3 Create the folder for example ../vsphere/ - -2.4 Copy all files from my folder /Terraform into your Terraform project - -2.5 Type the commands : - - #cd /your folder - - #terraform init - - -Ansible -------- - -3.1 Create a UNIX instance - -3.2 Download and install Ansible - -3.3 Create the folder for example /root/vsphere/ - -3.4 Copy all files from my folder /Ansible into your Ansible project (ansible.cfg, instance.yml and /group_vars) - -Start ------ - -4.1 Type the commands on your Terrafom instance: - - #cd /your folder - - #terraform plan - - #terraform apply - - #yes - diff --git a/docs/configexamples/index.rst b/docs/configexamples/index.rst index 7134e14c..d5973eb2 100644 --- a/docs/configexamples/index.rst +++ b/docs/configexamples/index.rst @@ -17,6 +17,7 @@ This chapter contains various configuration examples: wan-load-balancing pppoe-ipv6-basic l3vpn-hub-and-spoke + lac-lns inter-vrf-routing-vrf-lite qos segment-routing-isis diff --git a/docs/configexamples/lac-lns.rst b/docs/configexamples/lac-lns.rst new file mode 100644 index 00000000..b246c4d3 --- /dev/null +++ b/docs/configexamples/lac-lns.rst @@ -0,0 +1,169 @@ +:lastproofread: 2024-02-21 + +.. _examples-lac-lns: + +############### +PPPoE over L2TP +############### + +This document is to describe a basic setup using PPPoE over L2TP. +LAC and LNS are components of the broadband topology. +LAC - L2TP access concentrator +LNS - L2TP Network Server +LAC and LNS forms L2TP tunnel. LAC receives packets from PPPoE clients and +forward them to LNS. LNS is the termination point that comes from PPP packets +from the remote client. + +In this example we use VyOS 1.5 as LNS and Cisco IOS as LAC. +All users with domain **vyos.io** will be tunneled to LNS via L2TP. + +Network Topology +================ + +.. image:: /_static/images/lac-lns-diagram.jpg + :width: 60% + :align: center + :alt: Network Topology Diagram + +Configurations +============== + +LAC +--- + +.. code-block:: none + + aaa new-model + ! + aaa authentication ppp default local + ! + vpdn enable + vpdn aaa attribute nas-ip-address vpdn-nas + ! + vpdn-group LAC + request-dialin + protocol l2tp + domain vyos.io + initiate-to ip 192.168.139.100 + source-ip 192.168.139.101 + local name LAC + l2tp tunnel password 0 test123 + ! + bba-group pppoe MAIN-BBA + virtual-template 1 + ! + interface GigabitEthernet0/0 + description To LNS + ip address 192.168.139.101 255.255.255.0 + duplex auto + speed auto + media-type rj45 + ! + interface GigabitEthernet0/1 + description To PPPoE clients + no ip address + duplex auto + speed auto + media-type rj45 + pppoe enable group MAIN-BBA + ! + +LNS +--- + +.. code-block:: none + + set interfaces ethernet eth0 address '192.168.139.100/24' + set nat source rule 100 outbound-interface name 'eth0' + set nat source rule 100 source address '10.0.0.0/24' + set nat source rule 100 translation address 'masquerade' + set protocols static route 0.0.0.0/0 next-hop 192.168.139.2 + set vpn l2tp remote-access authentication mode 'radius' + set vpn l2tp remote-access authentication radius server 192.168.139.110 key 'radiustest' + set vpn l2tp remote-access client-ip-pool TEST-POOL range '10.0.0.2-10.0.0.100' + set vpn l2tp remote-access default-pool 'TEST-POOL' + set vpn l2tp remote-access gateway-address '10.0.0.1' + set vpn l2tp remote-access lns host-name 'LAC' + set vpn l2tp remote-access lns shared-secret 'test123' + set vpn l2tp remote-access name-server '8.8.8.8' + set vpn l2tp remote-access ppp-options disable-ccp + +.. note:: This setup requires the Compression Control Protocol (CCP) + being disabled, the command ``set vpn l2tp remote-access ppp-options disable-ccp`` + accomplishes that. + +Client +------ + +In this lab we use Windows PPPoE client. + +.. image:: /_static/images/lac-lns-winclient.jpg + :width: 100% + :align: center + :alt: Window PPPoE Client Configuration + +Monitoring +---------- + +Monitoring on LNS side + +.. code-block:: none + + vyos@vyos:~$ show l2tp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + --------+--------------+----------+-----+--------+-----------------+------------+--------+----------+-----------+---------- + l2tp0 | test@vyos.io | 10.0.0.2 | | | 192.168.139.101 | | active | 00:00:35 | 188.4 KiB | 9.3 MiB + +Monitoring on LAC side + +.. code-block:: none + + Router#show pppoe session + 1 session in FORWARDED (FWDED) State + 1 session total + Uniq ID PPPoE RemMAC Port VT VA State + SID LocMAC VA-st Type + 1 1 000c.290b.20a6 Gi0/1 1 N/A FWDED + 0c58.88ac.0001 + + Router#show l2tp + L2TP Tunnel and Session Information Total tunnels 1 sessions 1 + + LocTunID RemTunID Remote Name State Remote Address Sessn L2TP Class/ + Count VPDN Group + 23238 2640 LAC est 192.168.139.100 1 LAC + + LocID RemID TunID Username, Intf/ State Last Chg Uniq ID + Vcid, Circuit + 25641 25822 23238 test@vyos.io, Gi0/1 est 00:05:36 1 + +Monitoring on RADIUS Server side + +.. code-block:: none + + root@Radius:~# cat /var/log/freeradius/radacct/192.168.139.100/detail-20240221 + Wed Feb 21 13:37:17 2024 + User-Name = "test@vyos.io" + NAS-Port = 0 + NAS-Port-Id = "l2tp0" + NAS-Port-Type = Virtual + Service-Type = Framed-User + Framed-Protocol = PPP + Calling-Station-Id = "192.168.139.101" + Called-Station-Id = "192.168.139.100" + Acct-Status-Type = Start + Acct-Authentic = RADIUS + Acct-Session-Id = "45c731e169d9a4f1" + Acct-Session-Time = 0 + Acct-Input-Octets = 0 + Acct-Output-Octets = 0 + Acct-Input-Packets = 0 + Acct-Output-Packets = 0 + Acct-Input-Gigawords = 0 + Acct-Output-Gigawords = 0 + Framed-IP-Address = 10.0.0.2 + NAS-IP-Address = 192.168.139.100 + Event-Timestamp = "Feb 21 2024 13:37:17 UTC" + Tmp-String-9 = "ai:" + Acct-Unique-Session-Id = "ea6a1089816f19c0d0f1819bc61c3318" + Timestamp = 1708522637 diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index adccd92b..e63ac2c9 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -11,16 +11,16 @@ a deamonless container engine. Configuration ************* -.. cfgcmd:: set container name <name> image - +.. cfgcmd:: set container name <name> image + Sets the image name in the hub registry .. code-block:: none set container name mysql-server image mysql:8.0 - If a registry is not specified, Docker.io will be used as the container - registry unless an alternative registry is specified using + If a registry is not specified, Docker.io will be used as the container + registry unless an alternative registry is specified using **set container registry <name>** or the registry is included in the image name .. code-block:: none @@ -28,21 +28,21 @@ Configuration set container name mysql-server image quay.io/mysql:8.0 .. cfgcmd:: set container name <name> allow-host-networks - - Allow host networking in a container. The network stack of the container is + + Allow host networking in a container. The network stack of the container is not isolated from the host and will use the host IP. The following commands translate to "--net host" when the container - is created + is created .. note:: **allow-host-networks** cannot be used with **network** -.. cfgcmd:: set container name <name> network <networkname> +.. cfgcmd:: set container name <name> network <networkname> Attaches user-defined network to a container. Only one network must be specified and must already exist. -.. cfgcmd:: set container name <name> network <networkname> address <address> +.. cfgcmd:: set container name <name> network <networkname> address <address> Optionally set a specific static IPv4 or IPv6 address for the container. This address must be within the named network prefix. @@ -58,7 +58,7 @@ Configuration Add custom environment variables. Multiple environment variables are allowed. The following commands translate to "-e key=value" when the container - is created. + is created. .. code-block:: none @@ -88,7 +88,7 @@ Configuration set container name coredns volume 'corefile' source /config/coredns/Corefile set container name coredns volume 'corefile' destination /etc/Corefile - + .. cfgcmd:: set container name <name> volume <volumename> mode <ro | rw> Volume is either mounted as rw (read-write - default) or ro (read-only) @@ -107,9 +107,9 @@ Configuration - **always**: Restart containers when they exit, regardless of status, retrying indefinitely .. cfgcmd:: set container name <name> memory <MB> - + Constrain the memory available to the container. - + Default is 512 MB. Use 0 MB for unlimited memory. .. cfgcmd:: set container name <name> device <devicename> source <path> @@ -129,18 +129,49 @@ Configuration - **sys-time**: Permission to set system clock .. cfgcmd:: set container name <name> disable - + Disable a container. -.. cfgcmd:: set container network <networkname> +Container Networks +================== + +.. cfgcmd:: set container network <name> Creates a named container network +.. cfgcmd:: set container network <name> description + + A brief description what this network is all about. + +.. cfgcmd:: set container network <name> prefix <ipv4|ipv6> + + Define IPv4 or IPv6 prefix for a given network name. Only one IPv4 and + one IPv6 prefix can be used per network name. + +.. cfgcmd:: set container network <name> vrf <nme> + + Bind container network to a given VRF instance. + +Container Registry +================== + .. cfgcmd:: set container registry <name> Adds registry to list of unqualified-search-registries. By default, for any - image that does not include the registry in the image name, Vyos will use - docker.io as the container registry. + image that does not include the registry in the image name, VyOS will use + docker.io and quay.io as the container registry. + +.. cfgcmd:: set container registry <name> disable + + Disable a given container registry + +.. cfgcmd:: set container registry <name> authentication username +.. cfgcmd:: set container registry <name> authentication password + + Some container registries require credentials to be used. + + Credentials can be defined here and will only be used when adding a + container image to the system. ****************** @@ -148,7 +179,7 @@ Operation Commands ****************** .. opcmd:: add container image <containername> - + Pull a new image for container .. opcmd:: show container @@ -156,7 +187,7 @@ Operation Commands Show the list of all active containers. .. opcmd:: show container image - + Show the local container images. .. opcmd:: show container log <containername> @@ -175,7 +206,10 @@ Operation Commands Update container image +.. opcmd:: delete container image [image id|all] + Delete a particular container image based on it's image ID. + You can also delete all container images at once. ********************* Example Configuration @@ -196,7 +230,7 @@ Example Configuration set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' set container name mysql-server environment 'MYSQL_USER' value 'zabbix' set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' - set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' + set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest set container name zabbix-java-gateway network zabbix diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst index b37e95a2..65081e1c 100644 --- a/docs/configuration/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/pppoe.rst @@ -380,9 +380,13 @@ IPv6 DHCPv6-PD Example .. stop_vyoslinter -The following configuration will assign a /64 prefix out of a /56 delegation -to eth0. The IPv6 address assigned to eth0 will be <prefix>::ffff/64. -If you do not know the prefix size delegated to you, start with sla-len 0. +The following configuration will setup a PPPoE session source from eth1 and +assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0. +The IPv6 address assigned to eth0 will be <prefix>::1/64. If you do not know +the prefix size delegated to you, start with sla-len 0. + +In addition we setup IPv6 :abbr:`RA (Router Advertisements)` to make the +prefix known on the eth0 link. .. start_vyoslinter @@ -395,3 +399,5 @@ If you do not know the prefix size delegated to you, start with sla-len 0. set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' set interfaces pppoe pppoe0 ipv6 address autoconf set interfaces pppoe pppoe0 source-interface eth1 + + set service router-advert interface eth0 prefix ::/64 diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/index.rst index 1fea13ac..8fd6fbe8 100644 --- a/docs/configuration/pki/index.rst +++ b/docs/configuration/pki/index.rst @@ -2,6 +2,8 @@ .. include:: /_include/need_improvement.txt +.. _pki: + ### PKI ### @@ -118,12 +120,12 @@ OpenVPN .. opcmd:: generate pki openvpn shared-secret - Genearate a new OpenVPN shared secret. The generated secred is the output to + Genearate a new OpenVPN shared secret. The generated secret is the output to the console. .. opcmd:: generate pki openvpn shared-secret install <name> - Genearate a new OpenVPN shared secret. The generated secred is the output to + Genearate a new OpenVPN shared secret. The generated secret is the output to the console. .. include:: pki_cli_import_help.txt @@ -248,6 +250,35 @@ certificates used by services on this router. If CA is present, this certificate will be included in generated CRLs +Import files to PKI format +-------------------------- +VyOS provides this utility to import existing certificates/key files directly +into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the +/config folder permanently and will be retained post upgrade. + +.. opcmd:: import pki ca <name> file <Path to CA certificate file> + + Import the public CA certificate from the defined file to VyOS CLI. + +.. opcmd:: import pki ca <name> key-file <Path to private key file> + + Import the CAs private key portion to the CLI. This should never leave the + system as it is used to decrypt the data. The key is required if you use + VyOS as your certificate generator. + +.. opcmd:: import pki certificate <name> file <path to certificate> + + Import the certificate from the file to VyOS CLI. + +.. opcmd:: import pki certificate <name> key-file <path to private key> + + Import the private key of the certificate to the VyOS CLI. This should never + leave the system as it is used to decrypt the data. + +.. opcmd:: import pki openvpn shared-secret <name> file <path to OpenVPN secret key> + + Import the OpenVPN shared secret stored in file to the VyOS CLI. + ACME ^^^^ diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index ed4ade1a..64048552 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -1,5 +1,3 @@ -.. include:: /_include/need_improvement.txt - .. _ipoe_server: ########### @@ -24,8 +22,9 @@ functionality as PPPoE, but in a less robust manner. will restart the ppp daemon and will reset existing IPoE sessions, in order to become effective. -Configuration -============= +*********************** +Configuring IPoE Server +*********************** IPoE can be configure on different interfaces, it will depend on each specific situation which interface will provide IPoE to clients. The clients mac address @@ -39,158 +38,413 @@ the configuration. .. code-block:: none - set service ipoe-server authentication interface eth2 mac 08:00:27:2f:d8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server name-server '10.10.1.1' - set service ipoe-server name-server '10.10.1.2' - set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' + set interfaces ethernet eth1 address '192.168.0.1/24' + set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00 + set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01 + set service ipoe-server authentication mode 'local' + set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254' + set service ipoe-server default-pool 'IPOE-POOL' + set service ipoe-server gateway-address '192.168.0.1/24' + set service ipoe-server interface eth1 mode 'l2' + set service ipoe-server interface eth1 network 'vlan' + set service ipoe-server interface eth1 vlan '100-200' -The first address of the parameter ``client-subnet``, will be used as the -default gateway. Connected sessions can be checked via the ``show ipoe-server -sessions`` command. +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> -.. code-block:: none + Creates local IPoE user with username=**<interface>** and + password=**<MAC>** (mac-address) - vyos@vyos:~$ show ipoe-server sessions +.. cfgcmd:: set service ipoe-server authentication mode <local | radius> - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ - ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | | active | 00:45:05 | dccc870fd3134612 + Set authentication backend. The configured authentication backend is used + for all queries. + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + * **noauth**: Authentication disabled -IPv6 SLAAC and IA-PD --------------------- +.. cfgcmd:: set service ipoe-server client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> -To configure IPv6 assignments for clients, two options need to be configured. -A global prefix which is terminated on the clients cpe and a delegated prefix, -the client can use for devices routed via the clients cpe. + Use this command to define the first IP address of a pool of + addresses to be given to IPoE clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. -IPv6 DNS addresses are optional. +.. cfgcmd:: set service ipoe-server default-pool <POOL-NAME> -.. code-block:: none + Use this command to define default address pool name. - set service ipoe-server authentication interface eth3 mac 08:00:27:2F:D8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:1::/48' delegation-prefix '56' - set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8::/48' mask '64' - set service ipoe-server default-ipv6-pool IPv6-POOL - set service ipoe-server name-server '2001:db8::' - set service ipoe-server name-server '2001:db8:aaa::' - set service ipoe-server name-server '2001:db8:bbb::' - set service ipoe-server interface eth3 client-subnet '192.168.1.0/24' +.. cfgcmd:: set service ipoe-server gateway-address <x.x.x.x/x> + + Specifies address to be used as server ip address if radius can assign + only client address. In such case if client address is matched network + and mask then specified address and mask will be used. You can specify + multiple such options. + +.. cfgcmd:: set service ipoe-server interface <interface> mode <l2 | l3> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **l2**: It means that clients are on same network where interface + is.**(default)** + * **local**: It means that client are behind some router. + +.. cfgcmd:: set service ipoe-server interface <interface> network <shared | vlan> + + Specify where interface is shared by multiple users or it is vlan-per-user. + + * **shared**: Multiple clients share the same network. **(default)** + * **vlan**: One VLAN per client. .. code-block:: none - vyos@ipoe-server# run sh ipoe-server sessions - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+---------------------------------+-----------------+------------+--------+----------+------------------ - ipoe0 | eth3 | 08:00:27:2f:d8:06 | 192.168.1.2 | 2001:db8::a00:27ff:fe2f:d806/64 | 2001:db8:1::/56 | | active | 01:02:59 | 4626faf71b12cc25 + vyos@vyos:~$ show ipoe-server sessions + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime + --------+----------+-------------------+-------------+------------+------+------+--------+---------- + ipoe0 | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 | | ipoe | | active | 00:04:55 + ipoe1 | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 | | ipoe | | active | 00:04:44 -The clients :abbr:`CPE (Customer Premises Equipment)` can now communicate via -IPv4 or IPv6. All devices behind ``2001:db8::a00:27ff:fe2f:d806/64`` can use -addresses from ``2001:db8:1::/56`` and can globally communicate without the -need of any NAT rules. -Automatic VLAN creation ------------------------ +********************************* +Configuring RADIUS authentication +********************************* -To create VLANs per user during runtime, the following settings are required on -a per interface basis. VLAN ID and VLAN range can be present in the -configuration at the same time. +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. .. code-block:: none - set service ipoe-server interface eth2 network vlan - set service ipoe-server interface eth2 vlan-id 100 - set service ipoe-server interface eth2 vlan-id 200 - set service ipoe-server interface eth2 vlan-range 1000-2000 - set service ipoe-server interface eth2 vlan-range 2500-2700 + set service ipoe-server authentication mode radius + +.. cfgcmd:: set service ipoe-server authentication radius server <server> key <secret> -RADIUS Setup ------------- + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. -To use a RADIUS server for authentication and bandwidth-shaping, the following -example configuration can be used. +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: .. code-block:: none - set service ipoe-server authentication mode 'radius' - set service ipoe-server authentication radius server 10.100.100.1 key 'password' + set service ipoe-server authentication radius server 10.0.0.1 key 'foo' + set service ipoe-server authentication radius server 10.0.0.2 key 'foo' -Bandwidth Shaping -================= +.. note:: Some RADIUS severs use an access control list which allows or denies + queries, make sure to add your VyOS router to the allowed client list. -Bandwidth rate limits can be set for local users within the configuration or -via RADIUS based attributes. +RADIUS source address +===================== -Bandwidth Shaping for local users ---------------------------------- +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. -The rate-limit is set in kbit/sec. +.. cfgcmd:: set service ipoe-server authentication radius source-address <address> -.. code-block:: none + Source IPv4 address used in all RADIUS server queires. + +.. note:: The ``source-address`` must be configured on one of VyOS interface. + Best practice would be a loopback or dummy interface. + +RADIUS advanced options +======================= + +.. cfgcmd:: set service ipoe-server authentication radius server <server> port <port> + + Configure RADIUS `<server>` and its required port for authentication requests. + +.. cfgcmd:: set service ipoe-server authentication radius server <server> fail-time <time> + + Mark RADIUS server as offline for this given `<time>` in seconds. + +.. cfgcmd:: set service ipoe-server authentication radius server <server> disable + + Temporary disable this RADIUS server. + +.. cfgcmd:: set service ipoe-server authentication radius acct-timeout <timeout> + + Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +.. cfgcmd:: set service ipoe-server authentication radius dynamic-author server <address> + + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +.. cfgcmd:: set service ipoe-server authentication radius dynamic-author port <port> + + Port for Dynamic Authorization Extension server (DM/CoA) + +.. cfgcmd:: set service ipoe-server authentication radius dynamic-author key <secret> + + Secret for Dynamic Authorization Extension server (DM/CoA) + +.. cfgcmd:: set service ipoe-server authentication radius max-try <number> + + Maximum number of tries to send Access-Request/Accounting-Request queries + +.. cfgcmd:: set service ipoe-server authentication radius timeout <timeout> + + Timeout to wait response from server (seconds) + +.. cfgcmd:: set service ipoe-server authentication radius nas-identifier <identifier> + + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. + +.. cfgcmd:: set service ipoe-server authentication radius nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. + +.. cfgcmd:: set service ipoe-server authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. + +.. cfgcmd:: set service ipoe-server authentication radius rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is `Filter-Id`. + +.. note:: If you set a custom RADIUS attribute you must define it on both + dictionaries at RADIUS server and client. + +.. cfgcmd:: set service ipoe-server authentication radius rate-limit enable + + Enables bandwidth shaping via RADIUS. + +.. cfgcmd:: set service ipoe-server authentication radius rate-limit vendor + + Specifies the vendor dictionary, dictionary needs to be in + /usr/share/accel-ppp/radius. + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +Allocation clients ip addresses by RADIUS +========================================= + +If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP +address will be allocated to the client and the option ``default-pool`` within the CLI +config is being ignored. + +If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address +will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. + +If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` +whose name equals the attribute value. + +.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in + RFC6911. If they are not defined in your RADIUS server, add new dictionary_. - set service ipoe-server authentication interface eth2 mac 08:00:27:2f:d8:06 rate-limit download '500' - set service ipoe-server authentication interface eth2 mac 08:00:27:2f:d8:06 rate-limit upload '500' - set service ipoe-server authentication mode 'local' - set service ipoe-server name-server '10.10.1.1' - set service ipoe-server name-server '10.10.1.2' - set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom `ACCEL-PPP attribute`_. +Define it in your RADIUS server. + +**** +IPv6 +**** + +.. cfgcmd:: set service ipoe-server client-ipv6-pool <IPv6-POOL-NAME> prefix <address> + mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an IPoE client + will get an IPv6 prefix of your defined length (mask) to terminate the + IPoE endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. + +.. cfgcmd:: set service ipoe-server client-ipv6-pool <IPv6-POOL-NAME> delegate <address> + delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + IPoE. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. + +.. cfgcmd:: set service ipoe-server default-ipv6-pool <IPv6-POOL-NAME> + + Use this command to define default IPv6 address pool name. .. code-block:: none - vyos@vyos# run show ipoe-server sessions + set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' + set service ipoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set service ipoe-server default-ipv6-pool IPv6-POOL + +********* +Scripting +********* + +.. cfgcmd:: set service ipoe-server extended-scripts on-change <path_to_script> + + Script to run when session interface changed by RADIUS CoA handling + +.. cfgcmd:: set service ipoe-server extended-scripts on-down <path_to_script> + + Script to run when session interface going to terminate + +.. cfgcmd:: set service ipoe-server extended-scripts on-pre-up <path_to_script> + + Script to run before session interface comes up + +.. cfgcmd:: set service ipoe-server extended-scripts on-up <path_to_script> + + Script to run when session interface is completely configured and started + +**************** +Advanced Options +**************** + +Authentication Advanced Options +=============================== + +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> vlan + <vlan-id> + + VLAN monitor for automatic creation of VLAN interfaces for specific user on specific <interface> + +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> rate-limit + download <bandwidth> + + Download bandwidth limit in kbit/s for user on interface `<interface>`. + +.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC> rate-limit + upload <bandwidth> + + Upload bandwidth limit in kbit/s for for user on interface `<interface>`. + +Client IP Pool Advanced Options +=============================== + +.. cfgcmd:: set service ipoe-server client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ - ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb + Use this command to define the next address pool name. -Example -======= +Advanced Interface Options +============================== -* IPoE server will listen on interfaces eth1.50 and eth1.51 -* There are rate-limited and non rate-limited users (MACs) +.. cfgcmd:: set service ipoe-server interface <interface> client-subnet <x.x.x.x/x> -Server configuration --------------------- + Specify local range of ip address to give to dhcp clients. First IP in range is router IP. + If you need more customization use `client-ip-pool` + +.. cfgcmd:: set service ipoe-server interface <interface> external-dhcp dhcp-relay <x.x.x.x> + + Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed. + +.. cfgcmd:: set service ipoe-server interface <interface> external-dhcp giaddr <x.x.x.x> + + Specifies relay agent IP addre + + +Global Advanced options +======================= + +.. cfgcmd:: set service ipoe-server description <description> + + Set description. + +.. cfgcmd:: set service ipoe-server limits burst <value> + + Burst count + +.. cfgcmd:: set service ipoe-server limits connection-limit <value> + + Acceptable rate of connections (e.g. 1/min, 60/sec) + +.. cfgcmd:: set service ipoe-server limits timeout <value> + + Timeout in seconds + +.. cfgcmd:: set service ipoe-server max-concurrent-sessions + + Maximum number of concurrent session start attempts + +.. cfgcmd:: set service ipoe-server name-server <address> + + Connected client should use `<address>` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. + +.. cfgcmd:: set service ipoe-server shaper fwmark <1-2147483647> + + Match firewall mark value + +.. cfgcmd:: set service ipoe-server snmp master-agent + + Enable SNMP + +********** +Monitoring +********** + +.. opcmd:: show ipoe-server sessions + + Use this command to locally check the active sessions in the IPoE + server. .. code-block:: none - set interfaces dummy dum1000 address 100.64.0.1/32 - set interfaces dummy dum1000 address 2001:db8::1/128 + vyos@vyos:~$ show ipoe-server sessions + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime + ----------+----------+-------------------+-------------+------------+------+------+--------+---------- + eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 | | ipoe | | active | 03:03:58 - set interfaces ethernet eth1 description 'IPoE' - set interfaces ethernet eth1 vif 50 - set interfaces ethernet eth1 vif 51 +.. code-block:: none - set service ipoe-server authentication interface eth1.50 mac 00:0c:29:b7:49:a7 - set service ipoe-server authentication interface eth1.50 mac 00:0c:29:f0:be:4c rate-limit download '5000' - set service ipoe-server authentication interface eth1.50 mac 00:0c:29:f0:be:4c rate-limit upload '5000' - set service ipoe-server authentication interface eth1.51 mac 00:0c:29:b7:49:a7 rate-limit download '50000' - set service ipoe-server authentication interface eth1.51 mac 00:0c:29:b7:49:a7 rate-limit upload '50000' - set service ipoe-server authentication mode 'local' - - set service ipoe-server client-ipv6-pool IPv6-POOL delegate 2001:db8:ffff::/48 delegation-prefix '56' - set service ipoe-server client-ipv6-pool IPv6-POOL prefix 2001:db8:fffe::/48 mask '64' - set service ipoe-server default-ipv6-pool IPv6-POOL - set service ipoe-server interface eth1.50 client-subnet '100.64.50.0/24' - set service ipoe-server interface eth1.50 mode 'l2' - set service ipoe-server interface eth1.51 client-subnet '100.64.51.0/24' - set service ipoe-server interface eth1.51 mode 'l2' - set service ipoe-server name-server '100.64.0.1' - set service ipoe-server name-server '2001:db8::1' - -Client configuration --------------------- + vyos@vyos:~$ show ipoe-server statistics + uptime: 0.03:31:36 + cpu: 0% + mem(rss/virt): 6044/101360 kB + core: + mempool_allocated: 148628 + mempool_available: 144748 + thread_count: 1 + thread_active: 1 + context_count: 10 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 1 + timer_pending: 0 + sessions: + starting: 0 + active: 1 + finishing: 0 + ipoe: + starting: 0 + active: 1 + delayed: 0 + +************** +Toubleshooting +************** .. code-block:: none - set interfaces ethernet eth0 mac '00:0c:29:b7:49:a7' + vyos@vyos:~$sudo journalctl -u accel-ppp@ipoe -b 0 - set interfaces ethernet eth0 vif 50 address 'dhcp' - set interfaces ethernet eth0 vif 50 address 'dhcpv6' - set interfaces ethernet eth0 vif 50 dhcpv6-options pd 0 interface eth1 sla-id '1' + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started + Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] .. include:: /_include/common-references.txt +.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
\ No newline at end of file diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 56fcb968..99b3fbb5 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -13,13 +13,20 @@ be used with local authentication or a connected RADIUS server. changes/commits will restart the ppp daemon and will reset existing PPPoE connections from connected users, in order to become effective. -Configuration -============= +************************ +Configuring PPPoE Server +************************ +.. code-block:: none -First steps ------------ - + set service pppoe-server access-concentrator PPPoE-Server + set service pppoe-server authentication mode local + set service pppoe-server authentication local-users username test password 'test' + set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 + set service pppoe-server default-pool 'PPPOE-POOL' + set service pppoe-server outside-address 192.0.2.2 + set service pppoe-server gateway-address 192.168.255.1 + set service pppoe-server interface eth0 .. cfgcmd:: set service pppoe-server access-concentrator <name> @@ -28,14 +35,30 @@ First steps .. cfgcmd:: set service pppoe-server authentication mode <local | radius> - Use this command to define whether your PPPoE clients will locally - authenticate in your VyOS system or in RADIUS server. + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + * **noauth**: Authentication disabled. .. cfgcmd:: set service pppoe-server authentication local-users username <name> password <password> - Use this command to configure the username and the password of a - locally configured user. + Create `<user>` for local authentication on this system. The users password + will be set to `<pass>`. + +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> + + Use this command to define the first IP address of a pool of + addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. + +.. cfgcmd:: set service pppoe-server default-pool <POOL-NAME> + + Use this command to define default address pool name. .. cfgcmd:: set service pppoe-server interface <interface> @@ -44,124 +67,170 @@ First steps .. cfgcmd:: set service pppoe-server gateway-address <address> - Use this command to configure the local gateway IP address. + Specifies single `<gateway>` IP address to be used as local address of PPP + interfaces. -.. cfgcmd:: set service pppoe-server name-server <address> - Use this command to set the IPv4 or IPv6 address of every Doman Name - Server you want to configure. They will be propagated to PPPoE - clients. +********************************* +Configuring RADIUS authentication +********************************* +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. -Client Address Pools --------------------- +.. code-block:: none -To automatically assign the client an IP address as tunnel endpoint, a -client IP pool is needed. The source can be either RADIUS or a -named pool. There is possibility to create multiple named pools. -Each named pool can include only one address range. To use multiple -address ranges configure ``next-pool`` option. + set service pppoe-server authentication mode radius +.. cfgcmd:: set service pppoe-server authentication radius server <server> key <secret> -**Client IP address via IP range definition** + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. -.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: - Use this command to define the IP address range to be given - to PPPoE clients. If notation ``x.x.x.x-x.x.x.x``, - it must be within a /24 subnet. If notation ``x.x.x.x/x`` is - used there is possibility to set host/netmask. +.. code-block:: none -.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + set service pppoe-server authentication radius server 10.0.0.1 key 'foo' + set service pppoe-server authentication radius server 10.0.0.2 key 'foo' - Use this command to define the next address pool name. +.. note:: Some RADIUS severs use an access control list which allows or denies + queries, make sure to add your VyOS router to the allowed client list. -.. cfgcmd:: set service pppoe-server default-pool <POOL-NAME> +RADIUS source address +===================== - Use this command to define default address pool name. +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. -.. code-block:: none +.. cfgcmd:: set service pppoe-server authentication radius source-address <address> - set service pppoe-server client-ip-pool IP-POOL next-pool 'IP-POOL2' - set service pppoe-server client-ip-pool IP-POOL range '10.0.10.5/24' - set service pppoe-server client-ip-pool IP-POOL2 range '10.0.0.10-10.0.0.12' - set service pppoe-server default-pool 'IP-POOL' + Source IPv4 address used in all RADIUS server queires. +.. note:: The ``source-address`` must be configured on one of VyOS interface. + Best practice would be a loopback or dummy interface. -**RADIUS based IP pools (Framed-IP-Address)** +RADIUS advanced options +======================= -To use a radius server, you need to switch to authentication mode RADIUS -and then configure it. +.. cfgcmd:: set service pppoe-server authentication radius server <server> port <port> -.. cfgcmd:: set service pppoe-server authentication radius server <address> - key <secret> + Configure RADIUS `<server>` and its required port for authentication requests. - Use this command to configure the IP address and the shared secret - key of your RADIUS server. You can have multiple RADIUS servers - configured if you wish to achieve redundancy. +.. cfgcmd:: set service pppoe-server authentication radius server <server> fail-time <time> + Mark RADIUS server as offline for this given `<time>` in seconds. -.. code-block:: none +.. cfgcmd:: set service pppoe-server authentication radius server <server> disable - set service pppoe-server access-concentrator 'ACN' - set service pppoe-server authentication mode 'radius' - set service pppoe-server authentication radius server 10.1.100.1 key 'secret' - set service pppoe-server interface 'eth1' - set service pppoe-server gateway-address '10.1.1.2' + Temporary disable this RADIUS server. -RADIUS provides the IP addresses in the example above via -Framed-IP-Address. +.. cfgcmd:: set service pppoe-server authentication radius acct-timeout <timeout> -**RADIUS sessions management DM/CoA** + Timeout to wait reply for Interim-Update packets. (default 3 seconds) -.. cfgcmd:: set service pppoe-server authentication radius dynamic-author - <key | port | server> +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author server <address> - Use this command to configure Dynamic Authorization Extensions to - RADIUS so that you can remotely disconnect sessions and change some - authentication parameters. + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) -.. code-block:: none +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author port <port> - set service pppoe-server authentication radius dynamic-author key 'secret123' - set service pppoe-server authentication radius dynamic-author port '3799' - set service pppoe-server authentication radius dynamic-author server '10.1.1.2' + Port for Dynamic Authorization Extension server (DM/CoA) +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author key <secret> -Example, from radius-server send command for disconnect client with -username test + Secret for Dynamic Authorization Extension server (DM/CoA) -.. code-block:: none +.. cfgcmd:: set service pppoe-server authentication radius max-try <number> - root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 - disconnect secret123 + Maximum number of tries to send Access-Request/Accounting-Request queries -You can also use another attributes for identify client for disconnect, -like Framed-IP-Address, Acct-Session-Id, etc. Result commands appears in -log. +.. cfgcmd:: set service pppoe-server authentication radius timeout <timeout> -.. code-block:: none + Timeout to wait response from server (seconds) - show log | match Disconnect* +.. cfgcmd:: set service pppoe-server authentication radius nas-identifier <identifier> -Example for changing rate-limit via RADIUS CoA. + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. -.. code-block:: none +.. cfgcmd:: set service pppoe-server authentication radius nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. + +.. cfgcmd:: set service pppoe-server authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. + +.. cfgcmd:: set service pppoe-server authentication radius rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is ``Filter-Id``. - echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa - secret123 +.. note:: If you set a custom RADIUS attribute you must define it on both + dictionaries at RADIUS server and client. -Filter-Id=5000/4000 (means 5000Kbit down-stream rate and 4000Kbit -up-stream rate) If attribute Filter-Id redefined, replace it in RADIUS -CoA request. +.. cfgcmd:: set service pppoe-server authentication radius rate-limit enable + + Enables bandwidth shaping via RADIUS. + +.. cfgcmd:: set service pppoe-server authentication radius rate-limit vendor + + Specifies the vendor dictionary, dictionary needs to be in + /usr/share/accel-ppp/radius. + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +Allocation clients ip addresses by RADIUS +========================================= + +If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP +address will be allocated to the client and the option ``default-pool`` within the CLI +config is being ignored. + +If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address +will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. + +If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` +whose name equals the attribute value. +.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in + RFC6911. If they are not defined in your RADIUS server, add new dictionary_. + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom `ACCEL-PPP attribute`_. +Define it in your RADIUS server. + +Renaming clients interfaces by RADIUS +===================================== + +If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be +renamed. + +.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 + characters, otherwise the interface won't be renamed. + + +*********************** Automatic VLAN Creation ------------------------ +*********************** .. cfgcmd:: set service pppoe-server interface <interface> vlan <id | range> VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module - named `vlan_mon`, which is monitoring incoming vlans and creates the + named ``vlan_mon``, which is monitoring incoming vlans and creates the necessary VLAN if required and allowed. VyOS supports the use of either VLAN ID's or entire ranges, both values can be defined at the same time for an interface. @@ -177,21 +246,26 @@ Automatic VLAN Creation set service pppoe-server interface eth3 vlan 500-1000 set service pppoe-server interface eth3 vlan 2000-3000 - +***************** Bandwidth Shaping ------------------ +***************** Bandwidth rate limits can be set for local users or RADIUS based attributes. For Local Users -^^^^^^^^^^^^^^^ +=============== + +.. cfgcmd:: set service pppoe-server authentication local-users username <user> rate-limit + download <bandwidth> + + Download bandwidth limit in kbit/s for `<user>`. -.. cfgcmd:: set service pppoe-server authentication local-users username <name> - rate-limit <download | upload> +.. cfgcmd:: set service pppoe-server authentication local-users username <user> rate-limit + upload <bandwidth> + + Upload bandwidth limit in kbit/s for `<user>`. - Use this command to configure a data-rate limit to PPPOoE clients for - traffic download or upload. The rate-limit is set in kbit/sec. .. code-block:: none @@ -209,7 +283,7 @@ For Local Users Once the user is connected, the user session is using the set limits and -can be displayed via 'show pppoe-server sessions'. +can be displayed via ``show pppoe-server sessions``. .. code-block:: none @@ -220,9 +294,9 @@ can be displayed via 'show pppoe-server sessions'. For RADIUS users -^^^^^^^^^^^^^^^^ +================ -The current attribute 'Filter-Id' is being used as default and can be +The current attribute ``Filter-Id`` is being used as default and can be setup within RADIUS: Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit @@ -238,9 +312,9 @@ setup and is working. Other attributes can be used, but they have to be in one of the dictionaries in */usr/share/accel-ppp/radius*. - +************** Load Balancing --------------- +************** .. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> @@ -262,71 +336,222 @@ allows other PPPoE servers send PADO faster and clients will connect to other servers. Last command says that this PPPoE server can serve only 3000 clients. - +**** IPv6 ----- +**** -IPv6 client's prefix -^^^^^^^^^^^^^^^^^^^^ +.. cfgcmd:: set service pppoe-server ppp-options ipv6 <require | prefer | allow | deny> -.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> - prefix <address> mask <number-of-bits> + Specifies IPv6 negotiation preference. - Use this comand to set the IPv6 address pool from which a PPPoE - client will get an IPv6 prefix of your defined length (mask) to - terminate the PPPoE endpoint at their side. The mask length can be - set from 48 to 128 bit long, the default value is 64. + * **require** - Require IPv6 negotiation + * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv6 only if client requests + * **deny** - Do not negotiate IPv6 (default value) +.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> prefix <address> + mask <number-of-bits> -IPv6 Prefix Delegation -^^^^^^^^^^^^^^^^^^^^^^ + Use this comand to set the IPv6 address pool from which an PPPoE client + will get an IPv6 prefix of your defined length (mask) to terminate the + PPPoE endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. -.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> - delegate <address> delegation-prefix <number-of-bits> +.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> delegate <address> + delegation-prefix <number-of-bits> - Use this command to configure DHCPv6 Prefix Delegation (RFC3633). You - will have to set your IPv6 pool and the length of the delegation - prefix. From the defined IPv6 pool you will be handing out networks - of the defined length (delegation-prefix). The length of the - delegation prefix can be set from 32 to 64 bit long. + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + PPPoE. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. +.. cfgcmd:: set service pppoe-server default-ipv6-pool <IPv6-POOL-NAME> -IPv6 default client's pool assignment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Use this command to define default IPv6 address pool name. -.. cfgcmd:: set service pppoe-server default-ipv6-pool <POOL-NAME> +.. code-block:: none - Use this command to define default IPv6 address pool name. + set service pppoe-server ppp-options ipv6 allow + set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' + set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set service pppoe-server default-ipv6-pool IPv6-POOL +IPv6 Advanced Options +===================== +.. cfgcmd:: set service pppoe-server ppp-options ipv6-accept-peer-interface-id -Maintenance mode -================ + Accept peer interface identifier. By default is not defined. + +.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies fixed or random interface identifier for IPv6. + By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + +.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies peer interface identifier for IPv6. By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + * **ipv4-addr** - Calculate interface identifier from IPv4 address. + * **calling-sid** - Calculate interface identifier from calling-station-id. + +********* +Scripting +********* -.. opcmd:: set pppoe-server maintenance-mode <enable | disable> +.. cfgcmd:: set service pppoe-server extended-scripts on-change <path_to_script> - For network maintenance, it's a good idea to direct users to a backup - server so that the primary server can be safely taken out of service. - It's possible to switch your PPPoE server to maintenance mode where - it maintains already established connections, but refuses new - connection attempts. + Script to run when session interface changed by RADIUS CoA handling +.. cfgcmd:: set service pppoe-server extended-scripts on-down <path_to_script> -Checking connections + Script to run when session interface going to terminate + +.. cfgcmd:: set service pppoe-server extended-scripts on-pre-up <path_to_script> + + Script to run before session interface comes up + +.. cfgcmd:: set service pppoe-server extended-scripts on-up <path_to_script> + + Script to run when session interface is completely configured and started + +**************** +Advanced Options +**************** + +Authentication Advanced Options +=============================== + +.. cfgcmd:: set service pppoe-server authentication local-users username <user> disable + + Disable `<user>` account. + +.. cfgcmd:: set service pppoe-server authentication local-users username <user> static-ip + <address> + + Assign static IP address to `<user>` account. + +.. cfgcmd:: set service pppoe-server authentication protocols + <pap | chap | mschap | mschap-v2> + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. + +Client IP Pool Advanced Options +=============================== + +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. + +PPP Advanced Options ==================== -.. opcmd:: show pppoe-server sessions +.. cfgcmd:: set service pppoe-server ppp-options disable-ccp - Use this command to locally check the active sessions in the PPPoE - server. + Disable Compression Control Protocol (CCP). + CCP is enabled by default. +.. cfgcmd:: set service pppoe-server ppp-options interface-cache <number> -.. code-block:: none + Specifies number of interfaces to keep in cache. It means that don’t + destroy interface after corresponding session is destroyed, instead + place it to cache and use it later for new sessions repeatedly. + This should reduce kernel-level interface creation/deletion rate lack. + Default value is **0**. - show pppoe-server sessions - ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- - ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +.. cfgcmd:: set service pppoe-server ppp-options ipv4 <require | prefer | allow | deny> + + Specifies IPv4 negotiation preference. + + * **require** - Require IPv4 negotiation + * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv4 only if client requests (Default value) + * **deny** - Do not negotiate IPv4 + +.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-failure <number> + + Defines the maximum `<number>` of unanswered echo requests. Upon reaching the + value `<number>`, the session will be reset. Default value is **3**. + +.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-interval <interval> + + If this option is specified and is greater than 0, then the PPP module will + send LCP pings of the echo request every `<interval>` seconds. + Default value is **30**. + +.. cfgcmd:: set service pppoe-server ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. Default value is **0**. + +.. cfgcmd:: set service pppoe-server ppp-options min-mtu <number> + + Defines minimum acceptable MTU. If client will try to negotiate less then + specified MTU then it will be NAKed or disconnected if rejects greater MTU. + Default value is **100**. + +.. cfgcmd:: set service pppoe-server ppp-options mppe <require | prefer | deny> + + Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotiation + preference. + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) + * **deny** - deny mppe + + Default behavior - don't ask client for mppe, but allow it if client wants. + Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy + attribute. + +.. cfgcmd:: set service pppoe-server ppp-options mru <number> + + Defines preferred MRU. By default is not defined. + +Global Advanced options +======================= + +.. cfgcmd:: set service pppoe-server description <description> + + Set description. + +.. cfgcmd:: set service pppoe-server limits burst <value> + + Burst count + +.. cfgcmd:: set service pppoe-server limits connection-limit <value> + + Acceptable rate of connections (e.g. 1/min, 60/sec) + +.. cfgcmd:: set service pppoe-server limits timeout <value> + + Timeout in seconds + +.. cfgcmd:: set service pppoe-server mtu + + Maximum Transmission Unit (MTU) (default: **1492**) + +.. cfgcmd:: set service pppoe-server max-concurrent-sessions + + Maximum number of concurrent session start attempts + +.. cfgcmd:: set service pppoe-server name-server <address> + + Connected client should use `<address>` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. + +.. cfgcmd:: set service pppoe-server service-name <names> + + Specifies Service-Name to respond. If absent any Service-Name is + acceptable and client’s Service-Name will be sent back. Also possible + set multiple service-names: `sn1,sn2,sn3` Per default the user session is being replaced if a second authentication request succeeds. Such session requests can be either @@ -335,23 +560,48 @@ user in the latter case. If it is denied, the second session is being rejected even if the authentication succeeds, the user has to terminate its first session and can then authentication again. -.. code-block:: none +.. cfgcmd:: set service pppoe-server session-control + + * **disable**: Disables session control. + * **deny**: Deny second session authorization. + * **replace**: Terminate first session when second is authorized **(default)** + +.. cfgcmd:: set service pppoe-server shaper fwmark <1-2147483647> - vyos@# set service pppoe-server session-control - Possible completions: - disable Disables session control - deny Deny second session authorization + Match firewall mark value +.. cfgcmd:: set service pppoe-server snmp master-agent + Enable SNMP +.. cfgcmd:: set service pppoe-server wins-server <address> + Windows Internet Name Service (WINS) servers propagated to client + +********** +Monitoring +********** + +.. opcmd:: show pppoe-server sessions + + Use this command to locally check the active sessions in the PPPoE + server. + + +.. code-block:: none + + show pppoe-server sessions + ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- + ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +******** Examples -======== +******** IPv4 ----- +==== The example below uses ACN as access-concentrator name, assigns an address from the pool 10.1.1.100-111, terminates at the local endpoint @@ -372,9 +622,9 @@ address from the pool 10.1.1.100-111, terminates at the local endpoint Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation --------------------------------------------------------- +======================================================== -The example below covers a dual-stack configuration via pppoe-server. +The example below covers a dual-stack configuration. .. code-block:: none @@ -392,7 +642,7 @@ The example below covers a dual-stack configuration via pppoe-server. set service pppoe-server gateway-address '10.100.100.1' The client, once successfully authenticated, will receive an IPv4 and an -IPv6 /64 address to terminate the pppoe endpoint on the client side and +IPv6 /64 address to terminate the PPPoE endpoint on the client side and a /56 subnet for the clients internal use. .. code-block:: none @@ -403,3 +653,5 @@ a /56 subnet for the clients internal use. ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB .. include:: /_include/common-references.txt +.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
\ No newline at end of file diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index eb1a6844..f179153a 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -26,7 +26,7 @@ Supported interface types: Enabling Advertisments ~~~~~~~~~~~~~~~~~~~~~~~ -.. cfgcmd:: set service router-advert interface <interface> .... +.. cfgcmd:: set service router-advert interface <interface> ... .. stop_vyoslinter @@ -52,7 +52,11 @@ Enabling Advertisments Advertising a Prefix '''''''''''''''''''' -.. cfgcmd:: set service router-advert interface <interface> prefix 2001:DB8::/32 +.. cfgcmd:: set service router-advert interface <interface> prefix <prefix/mask> + + .. note:: You can also opt for using `::/64` as prefix for your :abbr:`RAs (Router + Advertisements)`. This will take the IPv6 GUA prefix assigned to the interface, + which comes in handy when using DHCPv6-PD. .. stop_vyoslinter diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst index 788765f0..02c889dd 100644 --- a/docs/configuration/system/option.rst +++ b/docs/configuration/system/option.rst @@ -24,7 +24,7 @@ General .. cfgcmd:: set system option root-partition-auto-resize - Enables the root partition auto-extension and resizes to the maximum + Enables the root partition auto-extension and resizes to the maximum available space on system boot. Kernel @@ -35,6 +35,23 @@ Kernel Disable all optional CPU mitigations. This improves system performance, but it may also expose users to several CPU vulnerabilities. + This will add the following option to the Kernel commandline: + + * ``mitigations=off`` + + .. note:: Setting will only become active with the next reboot! + +.. cfgcmd:: set system option kernel disable-power-saving + + Disable CPU power saving mechanisms also known as C states. + + This will add the following two options to the Kernel commandline: + + * ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle + * ``processor.max_cstate=1`` Limit processor to maximum C-state 1 + + .. note:: Setting will only become active with the next reboot! + *********** HTTP client *********** diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst index 93f69f80..3463592f 100644 --- a/docs/configuration/trafficpolicy/index.rst +++ b/docs/configuration/trafficpolicy/index.rst @@ -1203,6 +1203,8 @@ That is how it is possible to do the so-called "ingress shaping". set qos interface ifb0 egress MY-INGRESS-SHAPING set interfaces ethernet eth0 redirect ifb0 + set interfaces input ifb0 + .. warning:: Do not configure IFB as the first step. First create everything else diff --git a/docs/configuration/vpn/ipsec.rst b/docs/configuration/vpn/ipsec.rst index fad69bc3..172b3c64 100644 --- a/docs/configuration/vpn/ipsec.rst +++ b/docs/configuration/vpn/ipsec.rst @@ -32,10 +32,10 @@ for the cipher and hash. Adjust this as necessary. ************************************** IKE (Internet Key Exchange) Attributes ************************************** -IKE performs mutual authentication between two parties and establishes -an IKE security association (SA) that includes shared secret information -that can be used to efficiently establish SAs for Encapsulating Security -Payload (ESP) or Authentication Header (AH) and a set of cryptographic +IKE performs mutual authentication between two parties and establishes +an IKE security association (SA) that includes shared secret information +that can be used to efficiently establish SAs for Encapsulating Security +Payload (ESP) or Authentication Header (AH) and a set of cryptographic algorithms to be used by the SAs to protect the traffic that they carry. https://datatracker.ietf.org/doc/html/rfc5996 @@ -44,64 +44,64 @@ Multiple proposals can be specified in a single group. VyOS IKE group has the next options: -* ``close-action`` defines the action to take if the remote peer unexpectedly +* ``close-action`` defines the action to take if the remote peer unexpectedly closes a CHILD_SA: * ``none`` set action to none (default); - + * ``trap`` installs a trap policy for the CHILD_SA; - + * ``start`` tries to immediately re-create the CHILD_SA; - -* ``dead-peer-detection`` controls the use of the Dead Peer Detection protocol - (DPD, RFC 3706) where R_U_THERE notification messages (IKEv1) or empty - INFORMATIONAL messages (IKEv2) are periodically sent in order to check the + +* ``dead-peer-detection`` controls the use of the Dead Peer Detection protocol + (DPD, RFC 3706) where R_U_THERE notification messages (IKEv1) or empty + INFORMATIONAL messages (IKEv2) are periodically sent in order to check the liveliness of the IPsec peer: - + * ``action`` keep-alive failure action: - + * ``trap`` installs a trap policy, which will catch matching traffic and tries to re-negotiate the tunnel on-demand; - + * ``clear`` closes the CHILD_SA and does not take further action (default); - + * ``restart`` immediately tries to re-negotiate the CHILD_SA under a fresh IKE_SA; - + * ``interval`` keep-alive interval in seconds <2-86400> (default 30); - + * ``timeout`` keep-alive timeout in seconds <2-86400> (default 120) IKEv1 only - -* ``ikev2-reauth`` whether rekeying of an IKE_SA should also reauthenticate + +* ``ikev2-reauth`` whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1, reauthentication is always done. - Setting this parameter enables remote host re-authentication during an IKE + Setting this parameter enables remote host re-authentication during an IKE rekey. - + * ``key-exchange`` which protocol should be used to initialize the connection - If not set both protocols are handled and connections will use IKEv2 when + If not set both protocols are handled and connections will use IKEv2 when initiating, but accept any protocol version when responding: - + * ``ikev1`` use IKEv1 for Key Exchange; - + * ``ikev2`` use IKEv2 for Key Exchange; - + * ``lifetime`` IKE lifetime in seconds <0-86400> (default 28800); * ``disable-mobike`` disables MOBIKE Support. MOBIKE is only available for IKEv2 and enabled by default. - + * ``mode`` IKEv1 Phase 1 Mode Selection: - * ``main`` use Main mode for Key Exchanges in the IKEv1 Protocol + * ``main`` use Main mode for Key Exchanges in the IKEv1 Protocol (Recommended Default); - - * ``aggressive`` use Aggressive mode for Key Exchanges in the IKEv1 protocol + + * ``aggressive`` use Aggressive mode for Key Exchanges in the IKEv1 protocol aggressive mode is much more insecure compared to Main mode; - + * ``proposal`` the list of proposals and their parameters: * ``dh-group`` dh-group; - + * ``encryption`` encryption algorithm; * ``hash`` hash algorithm. @@ -111,8 +111,9 @@ VyOS IKE group has the next options: *********************************************** ESP (Encapsulating Security Payload) Attributes *********************************************** -ESP is used to provide confidentiality, data origin authentication, -connectionless integrity, an anti-replay service (a form of partial sequence + +ESP is used to provide confidentiality, data origin authentication, +connectionless integrity, an anti-replay service (a form of partial sequence integrity), and limited traffic flow confidentiality. https://datatracker.ietf.org/doc/html/rfc4303 @@ -122,26 +123,26 @@ Multiple proposals can be specified in a single group. VyOS ESP group has the next options: * ``compression`` Enables the IPComp(IP Payload Compression) protocol which - allows compressing the content of IP packets. - -* ``life-bytes`` ESP life in bytes <1024-26843545600000>. + allows compressing the content of IP packets. + +* ``life-bytes`` ESP life in bytes <1024-26843545600000>. Number of bytes transmitted over an IPsec SA before it expires; - -* ``life-packets`` ESP life in packets <1000-26843545600000>. - Number of packets transmitted over an IPsec SA before it expires; - -* ``lifetime`` ESP lifetime in seconds <30-86400> (default 3600). - How long a particular instance of a connection (a set of - encryption/authentication keys for user packets) should last, + +* ``life-packets`` ESP life in packets <1000-26843545600000>. + Number of packets transmitted over an IPsec SA before it expires; + +* ``lifetime`` ESP lifetime in seconds <30-86400> (default 3600). + How long a particular instance of a connection (a set of + encryption/authentication keys for user packets) should last, from successful negotiation to expiry; - + * ``mode`` the type of the connection: - + * ``tunnel`` tunnel mode (default); * ``transport`` transport mode; -* ``pfs`` whether Perfect Forward Secrecy of keys is desired on the +* ``pfs`` whether Perfect Forward Secrecy of keys is desired on the connection's keying channel and defines a Diffie-Hellman group for PFS: * ``enable`` Inherit Diffie-Hellman group from IKE group (default); @@ -155,20 +156,21 @@ VyOS ESP group has the next options: * ``encryption`` encryption algorithm (default 128 bit AES-CBC); * ``hash`` hash algorithm (default sha1). - + *********************************************** Options (Global IPsec settings) Attributes -*********************************************** +*********************************************** + * ``options`` * ``disable-route-autoinstall`` Do not automatically install routes to remote networks; - + * ``flexvpn`` Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco FlexVPN vendor ID payload (IKEv2 only), which is required in order to make Cisco brand devices allow negotiating a local traffic selector (from strongSwan's point of view) that is not the assigned virtual IP address if such an address is requested by strongSwan. Sending the Cisco FlexVPN vendor ID prevents the peer from narrowing the initiator's local traffic selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0 instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco template but should also work for GRE encapsulation; - + * ``interface`` Interface Name to use. The name of the interface on which virtual IP addresses should be installed. If not specified the addresses will be installed on the outbound interface; - + * ``virtual-ip`` Allows to install virtual-ip addresses. Comma separated list of virtual IPs to request in IKEv2 configuration payloads or IKEv1 Mode Config. The wildcard addresses 0.0.0.0 and :: request an arbitrary address, specific addresses may be defined. The responder may return a different address, though, or none at all. Define the ``virtual-address`` option to configure the IP address in site-to-site hierarchy. - + ************************* IPsec policy matching GRE ************************* @@ -266,7 +268,7 @@ However, now you need to make IPsec work with dynamic address on one side. The tricky part is that pre-shared secret authentication doesn't work with dynamic address, so we'll have to use RSA keys. -First, on both routers run the operational command "generate pki key-pair +First, on both routers run the operational command "generate pki key-pair install <key-pair name>". You may choose different length than 2048 of course. .. code-block:: none @@ -283,18 +285,18 @@ install <key-pair name>". You may choose different length than 2048 of course. set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' [edit] -Configuration commands for the private and public key will be displayed on the +Configuration commands for the private and public key will be displayed on the screen which needs to be set on the router first. -Note the command with the public key -(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). +Note the command with the public key +(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). Then do the same on the opposite router: .. code-block:: none vyos@left# run generate pki key-pair install ipsec-RIGHT -Note the command with the public key -(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). +Note the command with the public key +(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). Now the noted public keys should be entered on the opposite routers. @@ -363,3 +365,205 @@ On the RIGHT (dynamic address): set vpn ipsec site-to-site peer LEFT remote-address 192.0.2.10 set vpn ipsec site-to-site peer LEFT tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local set vpn ipsec site-to-site peer LEFT tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote + + +******************************************* +IKEv2 IPSec road-warriors remote-access VPN +******************************************* + +Internet Key Exchange version 2, IKEv2 for short, is a request/response +protocol developed by both Cisco and Microsoft. It is used to establish +and secure IPv4/IPv6 connections, be it a site-to-site VPN or from a +road-warrior connecting to a hub site. IKEv2, when run in point-to-multipoint, +or remote-access/road-warrior mode, secures the server-side with another layer +by using an x509 signed server certificate. + +Key exchange and payload encryption is still done using IKE and ESP proposals +as known from IKEv1 but the connections are faster to establish, more reliable, +and also support roaming from IP to IP (called MOBIKE which makes sure your +connection does not drop when changing networks from e.g. WIFI to LTE and back). + +This feature closely works together with :ref:`pki` subsystem as you required +a x509 certificate. + +Example +======= + +This example uses CACert as certificate authority. + +.. code-block:: + + set pki ca CAcert_Class_3_Root certificate 'MIIGPTCCBCWgAwIBAgIDFOIoMA0GCSqGSIb3DQEBDQUAMHkxEDAOBgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYSc3VwcG9ydEBjYWNlcnQub3JnMB4XDTIxMDQxOTEyMTgzMFoXDTMxMDQxNzEyMTgzMFowVDEUMBIGA1UEChMLQ0FjZXJ0IEluYy4xHjAcBgNVBAsTFWh0dHA6Ly93d3cuQ0FjZXJ0Lm9yZzEcMBoGA1UEAxMTQ0FjZXJ0IENsYXNzIDMgUm9vdDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAKtJNRFIfNImflOUz0Op3SjXQiqL84d4GVh8D57aiX3h++tykA10oZZkq5+gJJlz2uJVdscXe/UErEa4w75/ZI0QbCTzYZzA8pD6Ueb1aQFjww9W4kpCz+JEjCUoqMV5CX1GuYrz6fM0KQhF5Byfy5QEHIGoFLOYZcRD7E6CjQnRvapbjZLQ7N6QxX8KwuPr5jFaXnQ+lzNZ6MMDPWAzv/fRb0fEze5ig1JuLgiapNkVGJGmhZJHsK5I6223IeyFGmhyNav/8BBdwPSUp2rVO5J+TJAFfpPBLIukjmJ0FXFuC3ED6q8VOJrU0gVyb4z5K+taciX5OUbjchs+BMNkJyIQKopPWKcDrb60LhPtXapI19V91Cp7XPpGBFDkzA5CW4zt2/LP/JaT4NsRNlRiNDiPDGCbO5dWOK3z0luLoFvqTpa4fNfVoIZwQNORKbeiPK31jLvPGpKK5DR7wNhsX+kKwsOnIJpa3yxdUly6R9Wb7yQocDggL9V/KcCyQQNokszgnMyXS0XvOhAKq3A6mJVwrTWx6oUrpByAITGprmB6gCZIALgBwJNjVSKRPFbnr9s6JfOPMVTqJouBWfmh0VMRxXudA/Z0EeBtsSw/LIaRmXGapneLNGDRFLQsrJ2vjBDTn8Rq+G8T/HNZ92ZCdB6K4/jc0m+YnMtHmJVABfvpAgMBAAGjgfIwge8wDwYDVR0TAQH/BAUwAwEB/zBhBggrBgEFBQcBAQRVMFMwIwYIKwYBBQUHMAGGF2h0dHA6Ly9vY3NwLkNBY2VydC5vcmcvMCwGCCsGAQUFBzAChiBodHRwOi8vd3d3LkNBY2VydC5vcmcvY2xhc3MzLmNydDBFBgNVHSAEPjA8MDoGCysGAQQBgZBKAgMBMCswKQYIKwYBBQUHAgEWHWh0dHA6Ly93d3cuQ0FjZXJ0Lm9yZy9jcHMucGhwMDIGA1UdHwQrMCkwJ6AloCOGIWh0dHBzOi8vd3d3LmNhY2VydC5vcmcvY2xhc3MzLmNybDANBgkqhkiG9w0BAQ0FAAOCAgEAxh6td1y0KJvRyI1EEsC9dnYEgyEH+BGCf2vBlULAOBG1JXCNiwzB1Wz9HBoDfIv4BjGlnd5BKdSLm4TXPcE3hnGjH1thKR5dd3278K25FRkTFOY1gP+mGbQ3hZRB6IjDX+CyBqS7+ECpHTms7eo/mARN+Yz5R3lzUvXs3zSX+z534NzRg4i6iHNHWqakFcQNcA0PnksTB37vGD75pQGqeSmx51L6UzrIpn+274mhsaFNL85jhX+lKuk71MGjzwoThbuZ15xmkITnZtRQs6HhLSIqJWjDILIrxLqYHehK71xYwrRNhFb3TrsWaEJskrhveM0Os/vvoLNkh/L3iEQ5/LnmLMCYJNRALF7I7gsduAJNJrgKGMYvHkt1bo8uIXO8wgNV7qoU4JoaB1ML30QUqGcFr0TI06FFdgK2fwy5hulPxm6wuxW0v+iAtXYx/mRkwQpYbcVQtrIDvx1CT1k50cQxi+jIKjkcFWHw3kBoDnCos0/ukegPT7aQnk2AbL4c7nCkuAcEKw1BAlSETkfqi5btdlhh58MhewZv1LcL5zQyg8w1puclT3wXQvy8VwPGn0J/mGD4gLLZ9rGcHDUECokxFoWk+u5MCcVqmGbsyG4q5suS3CNslsHURfM8bQK4oLvHR8LCHEBMRcdFBn87cSvOK6eB1kdGKLA8ymXxZp8=' + set pki ca CAcert_Signing_Authority certificate 'MIIG7jCCBNagAwIBAgIBDzANBgkqhkiG9w0BAQsFADB5MRAwDgYDVQQKEwdSb290IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNBIENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRAY2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAOBgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYSc3VwcG9ydEBjYWNlcnQub3JnMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAziLA4kZ97DYoB1CW8qAzQIxL8TtmPzHlawI229Z89vGIj053NgVBlfkJ8BLPRoZzYLdufujAWGSuzbCtRRcMY/pnCujW0r8+55jE8Ez64AO7NV1sId6eINm6zWYyN3L69wj1x81YyY7nDl7qPv4coRQKFWyGhFtkZip6qUtTefWIonvuLwphK42yfk1WpRPs6tqSnqxEQR5YYGUFZvjARL3LlPdCfgv3ZWiYUQXw8wWRBB0bF4LsyFe7w2t6iPGwcswlWyCR7BYCEo8y6RcYSNDHBS4CMEK4JZwFaz+qOqfrU0j36NK2B5jcG8Y0f3/JHIJ6BVgrCFvzOKKrF11myZjXnhCLotLddJr3cQxyYN/Nb5gznZY0dj4kepKwDpUeb+agRThHqtdB7Uq3EvbXG4OKDy7YCbZZ16oE/9KTfWgu3YtLq1i6L43qlaegw1SJpfvbi1EinbLDvhG+LJGGi5Z4rSDTii8aP8bQUWWHIbEZAWV/RRyH9XzQQUxPKZgh/TMfdQwEUfoZd9vUFBzugcMd9Zi3aQaRIt0AUMyBMawSB3s42mhb5ivUfslfrejrckzzAeVLIL+aplfKkQABi6F1ITe1Yw1nPkZPcCBnzsXWWdsC4PDSy826YreQQejdIOQpvGQpQsgi3Hia/0PsmBsJUUtaWsJx8cTLc6nloQsCAwEAAaOCAX8wggF7MB0GA1UdDgQWBBQWtTIb1Mfz4OaO873SsDrusjkY0TAPBgNVHRMBAf8EBTADAQH/MDQGCWCGSAGG+EIBCAQnFiVodHRwOi8vd3d3LmNhY2VydC5vcmcvaW5kZXgucGhwP2lkPTEwMFYGCWCGSAGG+EIBDQRJFkdUbyBnZXQgeW91ciBvd24gY2VydGlmaWNhdGUgZm9yIEZSRUUgaGVhZCBvdmVyIHRvIGh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzAxBgNVHR8EKjAoMCagJKAihiBodHRwOi8vY3JsLmNhY2VydC5vcmcvcmV2b2tlLmNybDAzBglghkgBhvhCAQQEJhYkVVJJOmh0dHA6Ly9jcmwuY2FjZXJ0Lm9yZy9yZXZva2UuY3JsMDIGCCsGAQUFBwEBBCYwJDAiBggrBgEFBQcwAYYWaHR0cDovL29jc3AuY2FjZXJ0Lm9yZzAfBgNVHSMEGDAWgBQWtTIb1Mfz4OaO873SsDrusjkY0TANBgkqhkiG9w0BAQsFAAOCAgEAR5zXs6IX01JTt7Rq3b+bNRUhbO9vGBMggczo7R0qIh1kdhS6WzcrDoO6PkpuRg0L3qM7YQB6pw2V+ubzF7xl4C0HWltfzPTbzAHdJtjaJQw7QaBlmAYpN2CLB6Jeg8q/1Xpgdw/+IP1GRwdg7xUpReUA482l4MH1kf0W0ad94SuIfNWQHcdLApmno/SUh1bpZyeWrMnlhkGNDKMxCCQXQ360TwFHc8dfEAaq5ry6cZzm1oetrkSviE2qofxvv1VFiQ+9TX3/zkECCsUB/EjPM0lxFBmu9T5Ih+Eqns9ivmrEIQDv9tNyJHuLsDNqbUBal7OoiPZnXk9LH+qb+pLf1ofv5noy5vX2a5OKebHe+0Ex/A7e+G/HuOjVNqhZ9j5Nispfq9zNyOHGWD8ofj8DHwB50L1Xh5H+EbIoga/hJCQnRtxWkHP699T1JpLFYwapgplivF4TFv4fqp0nHTKC1x9gGrIgvuYJl1txIKmxXdfJzgscMzqpabhtHOMXOiwQBpWzyJkofF/w55e0LttZDBkEsilV/vW0CJsPs3eNaQF+iMWscGOkgLFlWsAS3HwyiYLNJo26aqyWPaIdc8E4ck7Sk08WrFrHIK3EHr4n1FZwmLpFAvucKqgl0hr+2jypyh5puA3KksHF3CsUzjMUvzxMhykh9zrMxQAHLBVrGwc=' + +After you obtained your server certificate you can import it from a file +on the local filesystem, or paste it into the CLI. Please note that +when entering the certificate manually you need to strip the +``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the certificate +or key needs to be presented in a single line without line breaks (``\n``). + +To import it from the filesystem use: + +.. code-block:: + + import pki certificate <name> file /path/to/cert.pem + +In our example the certificate name is called vyos: + +.. code-block:: + + set pki certificate vyos certificate 'MIIE45s...' + set pki certificate vyos private key 'MIIEvgI...' + +After the PKI certs are all set up we can start configuring our IPSec/IKE +proposals used for key-exchange end data encryption. The used encryption +ciphers and integrity algorithms vary from operating system to operating +system. The ones used in this post are validated to work on both Windows 10 +and iOS/iPadOS 14 to 17. + +.. code-block:: + + set vpn ipsec esp-group ESP-RW compression 'disable' + set vpn ipsec esp-group ESP-RW lifetime '3600' + set vpn ipsec esp-group ESP-RW pfs 'disable' + set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128' + set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256' + + set vpn ipsec ike-group IKE-RW key-exchange 'ikev2' + set vpn ipsec ike-group IKE-RW lifetime '7200' + set vpn ipsec ike-group IKE-RW mobike 'enable' + set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14' + set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128' + set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256' + +Every connection/remote-access pool we configure also needs a pool where +we can draw our client IP addresses from. We provide one IPv4 and IPv6 pool. +Authorized clients will receive an IPv4 address from the 192.0.2.128/25 prefix +and an IPv6 address from the 2001:db8:2000::/64 prefix. We can also send some +DNS nameservers down to our clients used on their connection. + +.. code-block:: + + set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1' + set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25' + set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1' + set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64' + +VyOS supports multiple IKEv2 remote-access connections. Every connection can +have its dedicated IKE/ESP ciphers, certificates or local listen address for +e.g. inbound load balancing. + +We configure a new connection named ``rw`` for road-warrior, that identifies +itself as ``192.0.2.1`` to the clients and uses the ``vyos`` certificate +signed by the `CAcert_Class3_Root`` intermediate CA. We select our previously +specified IKE/ESP groups and also link the IP address pool to draw addresses +from. + +.. code-block:: + + set vpn ipsec remote-access connection rw authentication id '192.0.2.1' + set vpn ipsec remote-access connection rw authentication server-mode 'x509' + set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'CAcert_Class_3_Root' + set vpn ipsec remote-access connection rw authentication x509 certificate 'vyos' + set vpn ipsec remote-access connection rw esp-group 'ESP-RW' + set vpn ipsec remote-access connection rw ike-group 'IKE-RW' + set vpn ipsec remote-access connection rw local-address '192.0.2.1' + set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4' + set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6' + +VyOS also supports (currently) two different modes of authentication, local and +RADIUS. To create a new local user named ``vyos`` with password ``vyos`` use the +following commands. + +.. code-block:: + + set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2' + set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos' + +If you feel better forwarding all authentication requests to your enterprises +RADIUS server, use the commands below. + +.. code-block:: + + set vpn ipsec remote-access connection rw authentication client-mode 'eap-radius' + set vpn ipsec remote-access radius server 192.0.2.2 key 'secret' + +Client Configuration +==================== + +Configuring VyOS to act as your IPSec access concentrator is one thing, but +you probably need to setup your client connecting to the server so they can +talk to the IPSec gateway. + +Microsoft Windows (10+) +----------------------- + +Windows 10 does not allow a user to choose the integrity and encryption ciphers +using the GUI and it uses some older proposals by default. A user can only +change the proposals on the client side by configuring the IPSec connection +profile via PowerShell. + +We generate a connection profile used by Windows clients that will connect to +the "rw" connection on our VyOS server on the VPN servers IP address/fqdn +`vpn.vyos.net`. + +.. note:: Microsoft Windows expects the server name to be also used in the + server's certificate common name, so it's best to use this DNS name for + your VPN connection. + +.. code-block:: + + vyos@vyos:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net + + ==== <snip> ==== + Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2" + Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force + ==== </snip> ==== + +As both Microsoft Windows and Apple iOS/iPadOS only support a certain set of +encryption ciphers and integrity algorithms we will validate the configured +IKE/ESP proposals and only list the compatible ones to the user — if multiple +are defined. If there are no matching proposals found — we can not generate a +profile for you. + +When first connecting to the new VPN the user is prompted to enter proper +credentials. + +Apple iOS/iPadOS (14.2+) +------------------------ + +Like on Microsoft Windows, Apple iOS/iPadOS out of the box does not expose +all available VPN options via the device GUI. + +If you want, need, and should use more advanced encryption ciphers (default +is still 3DES) you need to provision your device using a so-called "Device +Profile". A profile is a simple text file containing XML nodes with a +``.mobileconfig`` file extension that can be sent and opened on any device +from an E-Mail. + +Profile generation happens from the operational level and is as simple as +issuing the following command to create a profile to connect to the IKEv2 +access server at ``vpn.vyos.net`` with the configuration for the ``rw`` +remote-access connection group. + +.. note:: Apple iOS/iPadOS expects the server name to be also used in the + server's certificate common name, so it's best to use this DNS name for + your VPN connection. + +.. code-block:: + + vyos@vyos:~$ generate ipsec profile ios-remote-access rw remote vpn.vyos.net + + ==== <snip> ==== + <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> + <plist version="1.0"> + ... + </plist> + ==== </snip> ==== + +In the end, an XML structure is generated which can be saved as +``vyos.mobileconfig`` and sent to the device by E-Mail where it later can +be imported. + +During profile import, the user is asked to enter its IPSec credentials +(username and password) which is stored on the mobile. diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index ce3b6711..f0c60ec1 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -1,30 +1,80 @@ .. _l2tp: +#### L2TP ----- +#### VyOS utilizes accel-ppp_ to provide L2TP server functionality. It can be used with local authentication or a connected RADIUS server. -L2TP over IPsec -=============== - -Example for configuring a simple L2TP over IPsec VPN for remote access (works -with native Windows and Mac VPN clients): +*********************** +Configuring L2TP Server +*********************** .. code-block:: none - set vpn ipsec interface eth0 - - set vpn l2tp remote-access outside-address 192.0.2.2 + set vpn l2tp remote-access authentication mode local + set vpn l2tp remote-access authentication local-users username test password 'test' set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 set vpn l2tp remote-access default-pool 'L2TP-POOL' + set vpn l2tp remote-access outside-address 192.0.2.2 + set vpn l2tp remote-access gateway-address 192.168.255.1 + + +.. cfgcmd:: set vpn l2tp remote-access authentication mode <local | radius> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> password + <pass> + + Create `<user>` for local authentication on this system. The users password + will be set to `<pass>`. + +.. cfgcmd:: set vpn l2tp remote-access client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> + + Use this command to define the first IP address of a pool of + addresses to be given to l2tp clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. + +.. cfgcmd:: set vpn l2tp remote-access default-pool <POOL-NAME> + + Use this command to define default address pool name. + +.. cfgcmd:: set vpn l2tp remote-access gateway-address <gateway> + + Specifies single `<gateway>` IP address to be used as local address of PPP + interfaces. + +***************** +Configuring IPsec +***************** + +.. code-block:: none + + set vpn ipsec interface eth0 set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret> - set vpn l2tp remote-access authentication mode local - set vpn l2tp remote-access authentication local-users username test password 'test' -In the above example, an external IP of 192.0.2.2 is assumed. + +.. cfgcmd:: set vpn ipsec interface <INTERFACE> + + Use this command to define IPsec interface. + +.. cfgcmd:: set vpn l2tp remote-access ipsec-settings authentication mode <pre-shared-secret | x509> + + Set mode for IPsec authentication between VyOS and L2TP clients. + +.. cfgcmd:: set vpn l2tp remote-access ipsec-settings authentication mode <pre-shared-secret | x509> + + Set predefined shared secret phrase. + If a local firewall policy is in place on your external interface you will need to allow the ports below: @@ -64,156 +114,150 @@ To allow VPN-clients access via your external address, a NAT rule is required: set nat source rule 110 source address '192.168.255.0/24' set nat source rule 110 translation address masquerade +********************************* +Configuring RADIUS authentication +********************************* -VPN-clients will request configuration parameters, optionally you can DNS -parameter to the client. +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. .. code-block:: none - set vpn l2tp remote-access name-server '198.51.100.8' - set vpn l2tp remote-access name-server '198.51.100.4' - -Established sessions can be viewed using the **show l2tp-server sessions** -operational command + set vpn l2tp remote-access authentication mode radius -.. code-block:: none +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> key <secret> - vyos@vyos:~$ show l2tp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - --------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+---------- - l2tp0 | test | 192.168.255.3 | | | 192.168.0.36 | | active | 02:01:47 | 7.7 KiB | 1.2 KiB + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: +.. code-block:: none -LNS (L2TP Network Server) -========================= + set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' + set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' -LNS are often used to connect to a LAC (L2TP Access Concentrator). +.. note:: Some RADIUS_ severs use an access control list which allows or denies + queries, make sure to add your VyOS router to the allowed client list. -Below is an example to configure a LNS: +RADIUS source address +===================== -.. code-block:: none +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. - set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 - set vpn l2tp remote-access default-pool 'L2TP-POOL' - set vpn l2tp remote-access lns shared-secret 'secret' - set vpn l2tp remote-access ppp-options disable-ccp - set vpn l2tp remote-access authentication mode local - set vpn l2tp remote-access authentication local-users username test password 'test' +.. cfgcmd:: set vpn l2tp remote-access authentication radius source-address <address> -The example above uses 192.0.2.2 as external IP address. A LAC normally requires -an authentication password, which is set in the example configuration to -``lns shared-secret 'secret'``. This setup requires the Compression Control -Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access -ccp-disable`` accomplishes that. + Source IPv4 address used in all RADIUS server queires. +.. note:: The ``source-address`` must be configured on one of VyOS interface. + Best practice would be a loopback or dummy interface. -Bandwidth Shaping -================= +RADIUS advanced options +======================= -Bandwidth rate limits can be set for local users or via RADIUS based attributes. +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> port <port> -Bandwidth Shaping for local users -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Configure RADIUS `<server>` and its required port for authentication requests. -The rate-limit is set in kbit/sec. +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> fail-time <time> -.. code-block:: none + Mark RADIUS server as offline for this given `<time>` in seconds. - set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 - set vpn l2tp remote-access default-pool 'L2TP-POOL' - set vpn l2tp remote-access authentication mode local - set vpn l2tp remote-access authentication local-users username test password test - set vpn l2tp remote-access authentication local-users username test rate-limit download 20480 - set vpn l2tp remote-access authentication local-users username test rate-limit upload 10240 +.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> disable - vyos@vyos:~$ show l2tp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes - --------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+---------- - l2tp0 | test | 192.168.255.3 | | | 192.168.0.36 | | active | 02:01:47 | 7.7 KiB | 1.2 KiB + Temporary disable this RADIUS server. +.. cfgcmd:: set vpn l2tp remote-access authentication radius acct-timeout <timeout> -RADIUS authentication -====================== + Timeout to wait reply for Interim-Update packets. (default 3 seconds) -To enable RADIUS based authentication, the authentication mode needs to be -changed within the configuration. Previous settings like the local users, still -exists within the configuration, however they are not used if the mode has been -changed from local to radius. Once changed back to local, it will use all local -accounts again. +.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author server <address> -.. code-block:: none + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) - set vpn l2tp remote-access authentication mode <local|radius> +.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author port <port> -Since the RADIUS server would be a single point of failure, multiple RADIUS -servers can be setup and will be used subsequentially. + Port for Dynamic Authorization Extension server (DM/CoA) -.. code-block:: none +.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author key <secret> - set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' - set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' + Secret for Dynamic Authorization Extension server (DM/CoA) -.. note:: Some RADIUS_ severs use an access control list which allows or denies - queries, make sure to add your VyOS router to the allowed client list. +.. cfgcmd:: set vpn l2tp remote-access authentication radius max-try <number> -RADIUS source address -^^^^^^^^^^^^^^^^^^^^^ + Maximum number of tries to send Access-Request/Accounting-Request queries -If you are using OSPF as IGP, always the closest interface connected to the -RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests -to a single source IP e.g. the loopback interface. +.. cfgcmd:: set vpn l2tp remote-access authentication radius timeout <timeout> -.. code-block:: none + Timeout to wait response from server (seconds) - set vpn l2tp remote-access authentication radius source-address 10.0.0.3 +.. cfgcmd:: set vpn l2tp remote-access authentication radius nas-identifier <identifier> -Above command will use `10.0.0.3` as source IPv4 address for all RADIUS queries -on this NAS. + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. -.. note:: The ``source-address`` must be configured on one of VyOS interface. - Best practice would be a loopback or dummy interface. +.. cfgcmd:: set vpn l2tp remote-access authentication radius nas-ip-address <address> -RADIUS bandwidth shaping attribute -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. -To enable bandwidth shaping via RADIUS, the option rate-limit needs to be -enabled. +.. cfgcmd:: set vpn l2tp remote-access authentication radius source-address <address> -.. code-block:: none + Source IPv4 address used in all RADIUS server queires. - set vpn l2tp remote-access authentication radius rate-limit enable +.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit attribute <attribute> -The default RADIUS attribute for rate limiting is ``Filter-Id``, but you may -also redefine it. + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is `Filter-Id`. -.. code-block:: none +.. note:: If you set a custom RADIUS attribute you must define it on both + dictionaries at RADIUS server and client. - set vpn l2tp remote-access authentication radius rate-limit attribute Download-Speed +.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit enable -.. note:: If you set a custom RADIUS attribute you must define it on both - dictionaries at RADIUS server and client, which is the vyos router in our - example. + Enables bandwidth shaping via RADIUS. -The RADIUS dictionaries in VyOS are located at ``/usr/share/accel-ppp/radius/`` +.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit vendor -RADIUS advanced features -^^^^^^^^^^^^^^^^^^^^^^^^ + Specifies the vendor dictionary, dictionary needs to be in + /usr/share/accel-ppp/radius. Received RADIUS attributes have a higher priority than parameters defined within the CLI configuration, refer to the explanation below. Allocation clients ip addresses by RADIUS -***************************************** +========================================= If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP -address will be allocated to the client and the option ip-pool within the CLI +address will be allocated to the client and the option ``default-pool`` within the CLI config is being ignored. +If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address +will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. + +If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` +whose name equals the attribute value. + +.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in + RFC6911. If they are not defined in your RADIUS server, add new dictionary_. + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom `ACCEL-PPP attribute`_. +Define it in your RADIUS server. + Renaming clients interfaces by RADIUS -************************************* +===================================== If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be renamed. @@ -221,6 +265,301 @@ renamed. .. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 characters, otherwise the interface won't be renamed. +************************************* +Configuring LNS (L2TP Network Server) +************************************* + +LNS are often used to connect to a LAC (L2TP Access Concentrator). + +.. cfgcmd:: set vpn l2tp remote-access lns host-name <hostname> + + Sent to the client (LAC) in the Host-Name attribute + +.. cfgcmd:: set vpn l2tp remote-access lns shared-secret <secret> + + Tunnel password used to authenticate the client (LAC) + +To explain the usage of LNS follow our blueprint :ref:`examples-lac-lns`. + +**** +IPv6 +**** +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6 <require | prefer | allow | deny> + + Specifies IPv6 negotiation preference. + + * **require** - Require IPv6 negotiation + * **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv6 only if client requests + * **deny** - Do not negotiate IPv6 (default value) + +.. cfgcmd:: set vpn l2tp remote-access client-ipv6-pool <IPv6-POOL-NAME> prefix <address> + mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an l2tp client + will get an IPv6 prefix of your defined length (mask) to terminate the + l2tp endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. + +.. cfgcmd:: set vpn l2tp remote-access client-ipv6-pool <IPv6-POOL-NAME> delegate <address> + delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + l2tp. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. + +.. cfgcmd:: set vpn l2tp remote-access default-ipv6-pool <IPv6-POOL-NAME> + + Use this command to define default IPv6 address pool name. + +.. code-block:: none + + set vpn l2tp remote-access ppp-options ipv6 allow + set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' + set vpn l2tp remote-access client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set vpn l2tp remote-access default-ipv6-pool IPv6-POOL + +IPv6 Advanced Options +===================== +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id + + Accept peer interface identifier. By default is not defined. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies fixed or random interface identifier for IPv6. + By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-interface-id <random | x:x:x:x> + + Specifies peer interface identifier for IPv6. By default is fixed. + + * **random** - Random interface identifier for IPv6 + * **x:x:x:x** - Specify interface identifier for IPv6 + * **ipv4-addr** - Calculate interface identifier from IPv4 address. + * **calling-sid** - Calculate interface identifier from calling-station-id. + +********* +Scripting +********* + +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-change <path_to_script> + + Script to run when session interface changed by RADIUS CoA handling + +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-down <path_to_script> + + Script to run when session interface going to terminate + +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-pre-up <path_to_script> + + Script to run before session interface comes up + +.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-up <path_to_script> + + Script to run when session interface is completely configured and started + +**************** +Advanced Options +**************** + +Authentication Advanced Options +=============================== + +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> disable + + Disable `<user>` account. + +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> static-ip + <address> + + Assign static IP address to `<user>` account. + +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> rate-limit + download <bandwidth> + + Download bandwidth limit in kbit/s for `<user>`. + +.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> rate-limit + upload <bandwidth> + + Upload bandwidth limit in kbit/s for `<user>`. + +.. cfgcmd:: set vpn l2tp remote-access authentication protocols + <pap | chap | mschap | mschap-v2> + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. + +Client IP Pool Advanced Options +=============================== + +.. cfgcmd:: set vpn l2tp remote-access client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. + +PPP Advanced Options +==================== + +.. cfgcmd:: set vpn l2tp remote-access ppp-options disable-ccp + + Disable Compression Control Protocol (CCP). + CCP is enabled by default. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options interface-cache <number> + + Specifies number of interfaces to keep in cache. It means that don’t + destroy interface after corresponding session is destroyed, instead + place it to cache and use it later for new sessions repeatedly. + This should reduce kernel-level interface creation/deletion rate lack. + Default value is **0**. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv4 <require | prefer | allow | deny> + + Specifies IPv4 negotiation preference. + + * **require** - Require IPv4 negotiation + * **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects + * **allow** - Negotiate IPv4 only if client requests (Default value) + * **deny** - Do not negotiate IPv4 + +.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-failure <number> + + Defines the maximum `<number>` of unanswered echo requests. Upon reaching the + value `<number>`, the session will be reset. Default value is **3**. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-interval <interval> + + If this option is specified and is greater than 0, then the PPP module will + send LCP pings of the echo request every `<interval>` seconds. + Default value is **30**. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. Default value is **0**. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options min-mtu <number> + + Defines minimum acceptable MTU. If client will try to negotiate less then + specified MTU then it will be NAKed or disconnected if rejects greater MTU. + Default value is **100**. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options mppe <require | prefer | deny> + + Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotiation + preference. + + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail. (Default value) + * **deny** - deny mppe + + Default behavior - don't ask client for mppe, but allow it if client wants. + Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy + attribute. + +.. cfgcmd:: set vpn l2tp remote-access ppp-options mru <number> + + Defines preferred MRU. By default is not defined. + +Global Advanced options +======================= + +.. cfgcmd:: set vpn l2tp remote-access description <description> + + Set description. + +.. cfgcmd:: set vpn l2tp remote-access limits burst <value> + + Burst count + +.. cfgcmd:: set vpn l2tp remote-access limits connection-limit <value> + + Acceptable rate of connections (e.g. 1/min, 60/sec) + +.. cfgcmd:: set vpn l2tp remote-access limits timeout <value> + + Timeout in seconds + +.. cfgcmd:: set vpn l2tp remote-access mtu + + Maximum Transmission Unit (MTU) (default: **1436**) + +.. cfgcmd:: set vpn l2tp remote-access max-concurrent-sessions + + Maximum number of concurrent session start attempts + +.. cfgcmd:: set vpn l2tp remote-access name-server <address> + + Connected client should use `<address>` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. + +.. cfgcmd:: set vpn l2tp remote-access shaper fwmark <1-2147483647> + + Match firewall mark value + +.. cfgcmd:: set vpn l2tp remote-access snmp master-agent + + Enable SNMP + +.. cfgcmd:: set vpn l2tp remote-access wins-server <address> + + Windows Internet Name Service (WINS) servers propagated to client + +********** +Monitoring +********** + +.. code-block:: none + + vyos@vyos:~$ show l2tp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + --------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+---------- + l2tp0 | test | 192.168.255.3 | | | 192.168.0.36 | | active | 02:01:47 | 7.7 KiB | 1.2 KiB + +.. code-block:: none + + vyos@vyos:~$ show l2tp-server statistics + uptime: 0.02:49:49 + cpu: 0% + mem(rss/virt): 5920/100892 kB + core: + mempool_allocated: 133202 + mempool_available: 131770 + thread_count: 1 + thread_active: 1 + context_count: 5 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 3 + md_handler_pending: 0 + timer_count: 0 + timer_pending: 0 + sessions: + starting: 0 + active: 0 + finishing: 0 + l2tp: + tunnels: + starting: 0 + active: 0 + finishing: 0 + sessions (control channels): + starting: 0 + active: 0 + finishing: 0 + sessions (data channels): + starting: 0 + active: 0 + finishing: 0 + .. _`Google Public DNS`: https://developers.google.com/speed/public-dns .. _Quad9: https://quad9.net @@ -230,3 +569,5 @@ renamed. .. _FreeRADIUS: https://freeradius.org .. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server .. _accel-ppp: https://accel-ppp.org/ +.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 49f5aeb6..3acbed25 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -56,7 +56,7 @@ commands: set interfaces ethernet eth0 address dhcp set interfaces ethernet eth0 description 'OUTSIDE' set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces ethernet eth1 description 'INSIDE' + set interfaces ethernet eth1 description 'LAN' SSH Management |
