forked from inverse-inc/packetfence
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathUPGRADE
1280 lines (1025 loc) · 59.8 KB
/
UPGRADE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
PacketFence Upgrade Guide
=========================
http://www.packetfence.org/
Notes on upgrading from an older release.
Upgrading from a version prior to <stableRelease>
-------------------------------------------------
.LLDP Support
LLDP discovery of VoIP phones has been improved and streamlined. Let us know
if you experience any regressions or if you have switches that support LLDP
that you would like to see supported.
.Modification to the sites-available / sites-enabled for FreeRADIUS configuration.
We standardize the way to work with these two directories in the way that files in sites-enabled
are symlinks of files in sites-available. This way, modifications to files are less error prone.
Make sure to copy files from sites-enabled to sites-available before updating to avoid losing any changes made to
theses files. After the update, files that differs from originals will be saved as .rpmsave.
Upgrading from a version prior to 3.5.1
---------------------------------------
.Parser updates
Changes were made to the command parser. If you are using a packaged
distribution you have nothing to do. If you installed from source, you
will need to regenerate the precompiled grammar. Follow the instructions
in:
perldoc /usr/local/pf/lib/pf/pfcmd/pfcmd.pm
.Deprecation advance notice: `pf::node`'s `node_view_with_fingerprint`
`node_view_with_fingerprint` will be deprecated somewhere in 2013. Please
migrate your custom code to the faster `node_attributes_with_fingerprint`.
Upgrading from a version prior to 3.5.0
---------------------------------------
----
- Database schema update
New accounting violations and other violation related stuff needed some modifications
to the current database schema. Make sur you run the following to update
you schema EVEN IF YOU DON'T USE THE FEATURE:
mysql -u root -p pf -v < db/upgrade-3.3.0-3.5.0.sql
- RADIUS configuration is now in the PacketFence directory. You may need
to import custom configuration from /etc/raddb to pf/raddb. Note that
we now generates radiusd.conf, eap.conf, and sql.conf based on templates in
conf/. Especially important files to migrate would be packetfence.pm,
packetfence-soh.pm, proxy.conf, clients.conf, users and modules/mschap.
Additionally users running from source should make sure to migrate or create
DH parameters (this is handled automatically by the packages):
cd /usr/local/pf/raddb/certs; make dh
- FreeRADIUS user radiusd changed to pf
FreeRADIUS now runs as user `pf`. PEAP-MsCHAPv2 users will need to change
the ownership of the /var/lib/samba/winbindd_privileged/ directory so that
pf is the group owner. Other changes might be required based on your
configuration.
- Critical changes in FreeRADIUS watchdog
addons/watchdog/freeradius-watchdog.sh was updated. The previous version
of the watchdog on PacketFence 3.5.0 will simply kill radiusd and never
restart it. Unfortunately that change was made after 3.5.0 was released
so you need to get the latest watchdog from github:
https://github.com/inverse-inc/packetfence/raw/stable/addons/watchdog/freeradius-watchdog.sh
- Upgrade helper scripts
Very basic upgrade scripts for 3.5 were created in addons/upgrade/. See
their POD doc for usage information:
perldoc addons/upgrade/to-3.5-pf.conf.pl
- pf.conf interface gateway deprecated
The gateway=... parameters under every network interface is no longer
required. You will have to get rid of it (or run the above mentionned
upgrade helper script).
- pf.conf's general.caching deprecated
The caching=... parameter under [general] is no longer required. You
will have to get rid of it if you diverged from default configuration
which was disabled (or run the above mentionned upgrade helper script).
- Captive portal node status page removed
We deprecated a never used feature: /status inside the captive portal
who gave node information if the user was authenticated properly. This
made little sense since portal access is denied from users since a long
time. This was a legacy from the deprecated ARP mode.
- Captive portal variables consumption
Captive portal generation methods now consume portalSession object rather than
cgi, session and other variables. Please make sure to adapt your custom code (if needed)
in lib/pf/web/custom.pm.
- Nessus scan XMLRPC
We made some changes in the way nessus scan is working.
We directly use the policy on the server and you no longer have to declare
nessus_clientfile in pf.conf.
pf.conf's nessus_clientfile parameter has been dropped so make sure to
remove it (or run the upgrade helper script mentionned earlier).
- Bandwidth accounting violation changes
Triggers are no longer sliding windows but current day, week, month,
etc. instead. The trigger format changed. You should remove the digits
between size and duration. For example: TOT20GB1M becomes TOT20GBM.
- pf.conf's trapping.registration now enabled by default
We changed this setting from disabled to enabled by default since we consider
that registration is a whole part of the process. It is still possible to disable
this setting by overriding it's default value in pf.conf.
- dropping installation.pl and configurator.pl
We dropped both the installation.pl and configurator.pl scripts in favor of the
newly implemented web based configurator. Make sure to pay attention to the directives
at the end of the package installation.
- introduction of a new repository: OpenFusion
The use of perl Catalyst as a web engine for the new web platform required the introduction
of the OpenFusion repository. Make sure to take a quick look at the Administration Guide for
integration of this new repository.
----
Upgrading from a version prior to 3.3.0
---------------------------------------
----
- Database schema update
New sponsored guest feature and max nodes per user per category support
required database changes. Make sure you run the following to update
your schema even if you don't use the feature:
mysql -u root -p pf -v < db/upgrade-3.2.0-3.3.0.sql
Warning: If you are actively using RADIUS accounting features, please
note that the schema upgrade might take a while, we will create a new
index on the radacct table. Don't panic if it takes longer than usual!
- Changes to the FreeRADIUS integration
Due to a packaging glitch upgrading does not suffice to get updated files.
To do so:
# yum install packetfence-freeradius2
# yum reinstall packetfence-freeradius2
Note: Remember the --enablerepo=packetfence if you disabled the repo as
suggested in the admin guide.
Then re-add your virtual IP in radiusd.conf (if any) and your webservice
user password into /etc/raddb/packetfence.pm. Also, make sure to merge
the .rpmnew and .rpmsave files.
- new trigger types (no more scan type)
The trigger type "Scan" has been removed to leave place to two new types
(Nessus and Openvas). Due to that change, modification to existing
violations.conf is required to change all existing "Scan" type to "Nessus".
You can run the following command that will do the job. Make sure to backup
your existing violations.conf file.
/usr/bin/perl -p -i -e "s/Scan::/Nessus::/ig" /usr/local/pf/conf/violations.conf
- guests_pre_registration renamed to guests_admin_registration
Update your conf/pf.conf if you diverged from the default settings.
- Cisco wireless de-authentication
Cisco de-authentication now relies on RADIUS Disconnect-Request (RFC3576)
instead of SNMP or Telnet/SSH. Make sure you have set radiusSecret in your
conf/switches.conf and that RFC3576 support is properly enabled in your
controller's AAA config (the default is enabled since IOS 5.x+). Also
tightly firewalled environments will have to open up any port from
PacketFence up to port 3799 UDP to their the controllers.
- Important changes to the inline mode
We made some important changes to the way inline mode DNS is working.
We introduced DNS DNAT translation so that users in inline VLAN receive
a valid external DNS server by DHCP but if are in an unregistered or
isolated state, iptables DNATs the DNS traffic to a local DNS server on
the PacketFence server (exactly as in a vlan mode).
It is now important to change the previously recommended "disabled"
named setting to "enabled" in your conf/networks.conf for inline
interfaces. A warning message will come up on startup in case the setting
is still set as disabled in an inline configuration. We also dropped a
configuration parameter, inline.portal_redirect, so make sure to update
your pf.conf accordingly. Lastly, the gateway parameter in your inline
VLAN in conf/networks.conf should represent PacketFence's IP in that VLAN.
Don't hesitate to take a look at the revised configuration for the inline
mode in the PacketFence Administration Guide page 17.
- Email templates changed names
Related to the above guest API changes were several template files renamed
- emails-guest_registration.txt.tt -> emails-guest_preregistration.txt.tt
- emails-guest_activation.txt.tt -> emails-guest_email_activation.txt.tt
- emails-sponsor_activation.txt.tt ->
emails-guest_sponsor_activation.txt.tt
- var/dhcpd/dhcpd.leases no longer provided by package
The above file is no longer managed by our RPM package which means that
it's no longer overwritten by an empty file on upgrades. It is created on
demand if required when PacketFence starts.
- Web Authentication Modules API bump
In order to support sponsored guests, we made changes to our Web Auth API.
Make sure to integrate the isAllowedToSponsorGuests() sub in your
authentication modules and bump VERSION to 1.20. If you don't plan on
using the sponsored guests feature you can simply bump the API level.
- Changes to Guest API
Users with custom code will have to hook on these updated APIs
- pf::web::guest::generate_selfregistration_page's error reporting
- pf::web::guest::validate_selfregistration's error reporting
- pf::web::guest::web_sms_validation's error reporting
- pf::web::guest::generate_sms_confirmation_page's error reporting
- pf::web::guest relies on setting a 'guest_pid' session variable instead
of the login / username or token variables
- GUEST_TEMPLATE and SPONSOR_TEMPLATE templates changed names to
TEMPLATE_EMAIL_GUEST_ACTIVATION and TEMPLATE_EMAIL_SPONSOR_ACTIVATION
and moved from pf::email_activation into pf::web::guest
- pf::web::guest::send_registration_confirmation_email is now
pf::web::guest::send_template_email
- new API entry point prepare_email_guest_activation_info and
prepare_sponsor_guest_activation_info: these are meant to be overriden
by custom code to provide more information for email templates
- pf::web::guest::validate_sponsor_group() has been removed (migrated
into authentication modules)
- pf::web::guest::generate_activation_confirmation_page was renamed and
changed package, now: pf::web::generate_generic_page. It also changed
signature (now more generic).
- Changes to Web API
Users with custom code will have to hook on these updated APIs.
- pf::web::web_node_register now enforces max registered nodes per pid
limits. You might want to merge that in your custom code.
- pf::web::generate_error_page no longer performs the translation
itself, it is the burden of the caller to do so (to support format
strings)
- pf::radius API bump to 1.02
We bumped the version of our pf::radius API. If you want to take advantage
of the Role-based access control feature you should probably migrate your
custom authorize() call. Otherwise just bumping the version of your custom
extension should be fine.
- API Changes (pf::SNMP and pf::radius)
The final say of a RADIUS Access-Accept is now in a switch object (through
returnRadiusAccessAccept()) and no longer in pf::radius' authorize().
A new smaller indirection layer was introduced in pf::radius to allow
extensive rewrite of RADIUS Access-Accept in custom code. Check
pf::radius' _shouldRewriteAccessAccept and _rewriteAccessAccept.
- pf::SNMP API Bump
We changed the interface to radiusDisconnect. If you use that interface
in custom code (most, if not all, of you don't) then you'll need to update
your callers. We are now accepting an attributes hashref instead of the
accouting session id and username scalars.
----
Upgrading from a version prior to 3.2.0
---------------------------------------
----
- Database schema update
OpenVAS and billing engine support required database changes. Make sure you
run the following to update your schema even if you don't use one or both
of these new features:
mysql -u root -p pf -v < db/upgrade-3.1.0-3.2.0.sql
- Configuration changes related to OpenVAS integration
With the addition of OpenVAS as a scanning engine, we made changes to the
default configuration. People using nessus scan right now should be
careful and test their setup after the upgrade. They should at least set
their scan.engine to nessus (default is none). Also, if a custom port was
used, the scan.port parameter should be renamed to scan.nessus_port.
- Scan configuration changes
- scan.ssl no longer exists, get rid of it, it never really did anything
since 1.8.3.
- scan.nessusclient_file was renamed scan.nessus_clientfile
- scan.nessusclient_policy was renamed scan.nessus_clientpolicy
- scan.port was renamed scan.nessus_port
- Violations changes related to OpenVAS integration
There was some move in the example violations to add a new one for the
OpenVAS integration. Should pay attention to some
violations.conf.rpmsave / violations.conf.rpmnew
- New pf.conf configuration flag: registration.guests_self_registration
This parameter allows to enable or disable guest self-registration. It
deprecates the previous technique to disable this feature (set modes=).
It is enabled by default so when upgrading make sure to disable it if you
don't want to allow self-registered guests.
- Important changes to the FreeRADIUS integration
We made some important changes to our FreeRADIUS integration: a fix for
the random crashes, relocated logging to /var/log/radius/radius.log and a
2x performance improvement by avoiding superfluous queries. Due to a
packaging glitch upgrading does not suffice to get the goodness. To do so:
# yum install packetfence-freeradius2
# yum reinstall packetfence-freeradius2
Note: Remember the --enablerepo=packetfence if you disabled the repo as
suggested in the admin guide.
The re-add your virtual IP in radiusd.conf (if any) and your webservice
user password into /etc/raddb/packetfence.pm.
- new trigger types (no more scan type)
The trigger type "Scan" has been removed to leave place to two new types
(Nessus and Openvas). Due to that change, modification to existing
violations.conf is required to change all existing "Scan" type to "Nessus".
You can run the following command that will do the job. Make sure to backup
your existing violations.conf file.
/usr/bin/perl -p -i -e "s/Scan::/Nessus::/ig" /usr/local/pf/conf/violations.conf
- CLI (telnet/ssh) behavior change regarding privileged access
The feature to detect privileged access when using CLI access has been
disabled except in the Trapeze module where users are unpriviledged by
default. See #1370 for more details. Affected modules: most Cisco
switches with VoIP enabled and floating network devices, Cisco 3500XL,
Cisco ISR 18xx and Cisco WLC 21xx.
- Cisco Catalyst 3550 MAC-Auth / 802.1X
We changed the way we perform NAS-Port to ifIndex translation with this
release. If you use MAC-Auth (Cisco's MAB or 802.1X) and experience *any*
regression, please let us know.
- pfcmd exit status
Some exit status of pfcmd changed regarding the config sub-command.
----
Upgrading from a version prior to 3.1.0
---------------------------------------
----
- New repository required for RHEL 5 / CentOS 5: EPEL
Extra Packages for Enterprise Linux (EPEL) is a repository provided by
the Fedora project that we now rely upon. RHEL 6 / CentOS 6 users have it
already installed per installation instructions. Here's how to install it:
wget http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm
rpm -i epel-release-5-4.noarch.rpm
- rogue DHCP server violation
The rogue DHCP server violation now needs a trigger in order to work. Make
sure you have trigger=internal::1100010 under the violation entry. Users
of packaged versions should have appropriate config upgrade mechanism
handling the violation file.
- Changes to rogue DHCP server detection and pfdhcplistener
A lot of changes were made to the pfdhcplistener daemon. One big change
is that it will now detect rogue DHCP servers even on your normal VLANs
and routed VLANs (given that you forward your DHCP traffic to it). Make
sure that your dhcpservers configuration listing all authorized DHCP is
up to date.
- FreeRADIUS configuration changes
Due to the new SoH feature, you might need to reinstall the PacketFence
FreeRADIUS package.
yum reinstall --enablerepo=PacketFence packetfence-freeradius2
- Database schema update
SoH support and the MAC violation improvements required database changes.
Make sure you run the following to update your schema:
mysql -u root -p pf -v < db/upgrade-3.0.2-3.1.0.sql
- Aruba wireless de-authentication
Aruba de-authentication now relies on RADIUS Disconnect-Request (RFC3576)
instead of Telnet. Make sure you have set radiusSecret in your
conf/switches.conf and that RFC3576 support is properly enabled in your
controller's AAA config.
- Web library API change
Anyone who customized his web_node_register method will need to update his
version. _sanitize_and_register() now requires the session to be passed to
it.
- iptables marks changed
Mark 0 is no longer used. Unregistered nodes' packets are now set to mark
3. It was changed because rules matching mark 0 were matching unmarked
packets also. Unless you customized your firewall rules this change should
be transparent.
- DHCP Fingerprints loading behavior change
In order to improve performance, DHCP fingerprints are not re-imported on
every startup anymore. However updating fingerprints (pfcmd update
fingerprints) or reloading fingerprints (pfcmd reload fingerprints) will
still do.
- User-Agent database updated
We updated our User-Agent database. Some IDs could have changed in the
process. Most shouldn't have. The upstream project (HTTP::BrowserDetect)
accepted a patch from us to make this smoother in the future.
- dhcp_dumper.pl addon changes
Deep and important refactoring of the addon. Output format changed.
- SNMP traps limit mecanism
PacketFence can now limits the number of SNMP traps coming from a single
ifIndex. See pf/conf/documentation.conf under vlan for more infos.
- dropped jpgraph external library
We migrated out of jpgraph into a new javascript-based library for our
charts and graphs. Source users will have to create a webadmin_cache/
directory in var/. Packaged users won't have to do a thing.
----
Upgrading from a version prior to 3.0.3
---------------------------------------
----
- New dependency
This version introduces a new perl dependency: NetPacket. If you don't have
EPEL configured as a repository trying to upgrade might fail. To
successfully upgrade make sure you have the EPEL repository enabled.
- New time format
We are now using an ISO like format for time, s=seconds, m=minutes, D=days,
W=weeks, M=months, and Y=years. Make sure you adjust your configs,
especially your violations.conf.
----
Upgrading from a version prior to 3.0.2
---------------------------------------
----
- Database schema update
A new trigger has been added to delete the node useragent when deleting
a node. Make sure you run:
mysql -u root -p pf -v < db/upgrade-3.0.1-3.0.2.sql
- pf.conf configuration changes
- guests.self_allow_localdomain has been renamed
guests_self_registration.allow_localdomain
- advanced.adjustswitchportvlanscript has been dropped
- advanced.reevaluate_access_reasons's default value changed
- Default Firewall Rules Updated
Review the updated firewall rules (in .rpmnew) if you made changes and
make sure to integrate changes if you need them. New rules include:
- Allow incoming DNS on management interface (track production VLANs IPs)
- Changes to Inline API
Added a new method to pf::inline. Users with customized pf::inline::custom
will need to bump the API level to '1.01' after your changes are made (if
required) to stop PacketFence from complaining about correct API level.
- Changes to Guest API
- generate_activation_login_page is now generate_custom_login_page
- pf::web::guest::auth has been replaced by pf::web::web_user_authenticate
- pf::web::generate_login_page has been dropped. Use
generate_custom_login_page instead.
- Changes to captive portal Web API
Authentication objects are now created on every authentication attempt and
they can return connection specific state to the captive portal. For
example a more specific authentication error or additional attributes to be
recorded inside PacketFence.
- pf::web::web_user_authenticate no longer performs form validation.
validate_form is the one responsible now. Also it returns an instance
of the auth::* object after authentication. Users with custom code using
it will need to update their code.
- pf::web::validate_form is a new method to validate login forms
- Changes to authentication modules API
- $name is now a package global (declared with our) instead of a local
variable.
- authenticate returns only a true or false value. Errors meant for users
should be set with $this->_setLastError("string") in authenticate() sub.
- Some modules will require the import of pf::config. Add to the use
section on top: use pf::config qw($FALSE $TRUE);
Once the migration done, bump $VERSION to 1.10. You will *not* have to do
this if you made no customization to the conf/authentication/... files.
- pfcmd_vlan interface changes
reevaluateVlan is now called reevaluateAccess and will perform appropriate
changes for a firewall change too (inline enforcement).
----
Upgrading from a version prior to 3.0.1
---------------------------------------
----
- MySQL pf user rights
The user pf in the database is missing the execute rights. Make sure
you run :
mysql -u root -p pf -v < db/upgrade-3.0.0-3.0.1.sql
----
Upgrading from a version prior to 3.0.0
---------------------------------------
----
- BACKUP YOUR /usr/local/pf/ BEFORE UPGRADING
All files in html/user/ will be removed on upgrade (everything is now
in html/captive-portal/ as you'll see below). This includes templates and
remediation pages.
- Database schema update
Added support for guest self-registration / management. Also added support
for Radius accounting. New tables creation. You need to update your schema
with:
mysql -u root -p pf -v < db/upgrade-2.2.0-3.0.0.sql
- pf/vlan/custom.pm and pf/vlan/radius.pm API changes
Several variables were changed from bareword constants into Readonly
constants (to fix #1266). Some of you might need to adjust your
customizations to handle this change. Most of you won't need to. If you use
any of these constants in your customizations:
WIRELESS_802_1X, WIRELESS_MAC_AUTH, WIRED_802_1X, WIRED_MAC_AUTH,
WIRED_SNMP_TRAPS, WIRELESS, WIRED, EAP, UNKNOWN, INLINE, VOIP, NO_VOIP
Then you need to add a $ symbol in front of the constant's name.
All of you will need to bump the API level to '1.01' after your changes are
made (if required) to stop PacketFence from complaining about correct API
level.
- Upgrade helper scripts
Very basic upgrade scripts for 3.0 were created in addons/upgrade/. See
their POD doc for usage information:
perldoc addons/upgrade/to-3.0-networks.conf.pl
perldoc addons/upgrade/to-3.0-pf.conf.pl
perldoc addons/upgrade/to-3.0-violations.conf.pl
- Firewall (iptables) now handled by PacketFence
Make sure that the iptables generated will not conflict with the rules you
need for your environment. You can customize the default firewall
configuration in conf/iptables.conf. Also make sure that the iptables
service is started by your distro by default otherwise you will have
unnecessary error messages on PacketFence's startup.
- Several changes to Apache configuration
We've externalized repetitive portions in conf/httpd.conf.d/. Make sure to
re-integrate any customization you've made.
- violations.conf disable parameter deprecated in favor of enabled
disable=Y|N is no longer supported. Change with enabled=Y|N.
A helper upgrade script is provided in addons/upgrade/. See:
perldoc addons/upgrade/to-3.0-violations.conf.pl
- 'guest' category required for guest access
Newly added guest handling requires a 'guest' node category. Users upgrading
need to create it manually. See Node > Categories under the Web Admin or
`pfcmd help nodecategory`.
- New pf.conf configuration parameter: interface enforcement
Under the [interface ...] statements a new configuration parameter has been
added: enforcement. We got rid of the concept of 'modes' in PacketFence and
enforcement replaces that concept. It is a per interface choice allowing
you to run PacketFence in both inline and out-of-band mode at the same
time. Users upgrading should probably set enforcement=vlan on all interface
with type=internal. Run `bin/pfcmd checkup` to validate your configuration.
- conf/named_vlan.conf moved to conf/named.conf
People using packages should be automatically updated. Make sure to put
back any local changes you have made to the file. Others will need to move
the file. You can do so with:
mv /usr/local/pf/conf/named_vlan.conf /usr/local/pf/conf/named.conf
- conf/dhcpd_vlan.conf moved to conf/dhcpd.conf
People using packages should be automatically updated. Make sure to put
back any local changes you have made to the file. Others will need to move
the file. You can do so with:
mv /usr/local/pf/conf/dhcpd_vlan.conf /usr/local/pf/conf/dhcpd.conf
- vlan.dhcpd, vlan.named and vlan.radiusd moved under [services]
These variables are now located under [services] and they have a new
default value of enabled. Make sure to remove or migrate the old
configuration from your conf/pf.conf.
- services.httpd, dhcpd, named, radiusd, snmptrapd and snort renamed
They were all renamed to <name>_binary. Adapt your configuration if
required. Most users shouldn't have to.
- general.caching disabled by default
A historical and badly understood feature, general caching, has now been
disabled by default. Previously it only had impacts if the mode was ARP but
because of the modes removal it needed to be changed to disabled by default.
Please report any regression introduced by this change.
- pf.conf's scan.live_tids parameter removed
This "feature" has been removed because it created more confusion than
usefulness. Now every scan trigger ids specified in violations.conf have
full effect.
- networks.conf's pf_gateway= renamed next_hop=
Make sure to update your configuration otherwise you will get warnings on
startup. At some point in the future pf_gateway will no longer be supported.
- networks.conf's type change
isolation and registration keywords are replaced by vlan-isolation and
vlan-registration in networks.conf's type parameter. This is done to allow
the introduction of the inline keyword and avoid confusion between vlan and
inline enforcement over a network. It's recommended that you update your
configuration as the old names will be removed in the future. `pfcmd
checkup` will warn you about this.
- pf.conf parameter name and category changes
Here are the changes:
- vlan.adjustswitchportvlanscript is now advanced.adjustswitchportvlanscript
- vlan.adjustswitchportvlanreasons is now advanced.reevaluate_access_reasons
- ports.redirect is now inline.ports_redirect
You only need to take action if you are not using the default values.
- pf.conf's interface type changes
We added management keyword to replace the confusing managed keyword. Also
dhcp-listener is accepted in addition to the previously used dhcplistener.
Use of the managed keyword will issue warnings in `pfcmd checkup`.
- Dropping support of interface authorizedips
pf.conf's per interface authorizedips parameter no longer exists. We don't
belive if was used at all. If you want to achieve the same functionality
just edit conf/iptables.conf and add your own rules to allow specific IPs
in.
- flip.pl is no more
Its functionality has been merged into pfcmd_vlan under the -reevaluateVlan
flag. If you replaced system's flip.pl with your own you would like to know
that you will need to parse the -reevaluateVlan and -mac aa:bb:cc:dd:ee:ff
properly.
- Authentication modules interface change
All authentication modules (conf/authentication/*) were migrated into
objects. Please carefully merge any module you were using by comparing
the .rpmnew version and your version. If you are unsure, replace your
module with the .rpmnew one and re-apply configuration parameters
afterwards.
- Intrusive changes to Captive Portal
It is recommended that you redo your customization from scratch instead of
trying to adapt it.
Among other things:
- Changes to all templates, cgi-bin/ scripts and pf::web core code
- All remediation URLs have changed from /content/index.php to
/content/remediation.php. Make sure to update your conf/violations.conf!
- All URLs are now clean URLs translated by Apache's mod_rewrite config
- Default workflow now brings you to the login page (no more registration
click-through unless you adjust nbregpages in configuration)
- Default logo changed to packetfence-cp.png (was packetfence.png)
- Files organization was changed. Anything custom relying on specific paths
should be updated.
- html/user/ became html/captive-portal
- cgi-bin/ -> html/captive-portal/
- html/user/content/templates/ -> html/captive-portal/templates/
- html/user/content/violations/ -> html/captive-portal/violations/
- html/user/content/3rdparty/ -> html/captive-portal/content/
- Email Activation URL change
From /activate/<hash> to /activate/email/<hash>
- Support for Apache prior to version 2.2.0 dropped
Upgrade your Apache. We don't think it's used by anyone at this point. Let
us know if you need it back.
- register-$type.cgi no longer supported
If you relied on it, we suggest that you migrate your custom code into
lib/pf/web/custom.pm or the captive-portal's CGIs.
- jpgraph external library now included with distribution
Due to the lack of jpgraph packages, we decided to inline the software
instead of building packages for it. This simplifies installation from
tarball.
Jpgraph's installation used to be at
/usr/local/pf/html/admin/common/jpgraph/jpgraph-<version> but is now in
/usr/local/pf/lib/jpgraph. Users of our packaged versions won't notice the
change and can safely get rid of the php-jpgraph-packetfence package.
- jpgraph 1.x support deprecated
We got rid of the 1.x jpgraph support. It was only required for
environments still on PHP4. We don't think it's used by anyone at this
point. Let us know if you need it back.
- Nortal/Avaya ERS Switch module rename
We changed the naming of some Nortel/Avaya switch modules:
- Avaya::ERS5500 -> Avaya::ERS5000
- Avaya::ERS5500_6x -> Avaya::ERS5000_6x
- Nortel::ERS4500 -> Nortel::ERS4000
- Nortel::ERS5500 -> Nortel::ERS5000
- Nortel::ERS5500_6x -> Nortel::ERS5000_6x
- RADIUS Accounting
RADIUS is now using SQL to fetch the client configuration. So, for
every device that needs to do MAC Authentication (Wired/Wireless) or
802.1X, you need to add the radiusSecret=YOUR_SECRET to the
switches.conf entry for that device. Change YOUR_SECRET with the
actual RADIUS secret.
----
Upgrading from a version prior to 2.2.1
---------------------------------------
----
- Cisco port-security + Voice over IP support on 2960, 2970, 3550 and 4500
Changes (regressions?) in the Cisco 2960 IOS behavior in 12.2(46)SE or
greater forced us to change our VoIP handling behavior. If you run such an
IOS and have nodes behind the data port of your VoIP you need to upgrade
your switch configuration:
On every PacketFence port with VoIP add:
switchport port-security maximum 1 vlan voice
switchport port-security mac-address 0200.010x.xxxx vlan voice
where xxxxx is the ifIndex of the port under modification. See Network
Device Guide for a reminder of port to ifIndex translation for the 2960.
Above configuration should *not* be applied to IOS earlier than 12.2(46)SE
otherwise VoIP and/or device authorization will malfunction.
We think that the above mentionned changes should not be required on other
models than the 2960. Let us know if you experience otherwise.
- pf::vlan's $node_info changed
If you are using custom VLAN assignment code be aware that the $node_info
hashref is now populated by node_attributes() instead of node_view(). Most
important fields should still be available in $node_info however if you
needed one that is no longer there feel free to call node_view() yourself.
This was done to reduce the overall latency of RADIUS replies.
----
Upgrading from a version prior to 2.2.0
---------------------------------------
----
- Database schema update
Related to the easier User-Agent violation system, some tables were
dropped and others added. You need to update your schema with:
mysql -u root -p pf -v < db/upgrade-2.0.0-2.2.0.sql
- Configuration files location changed from conf/templates/ to conf/
Please make sure that you move your configuration files appropriately.
- SSL configuration changes
SSL Certificate statements are now stored in conf/ssl-certificates.conf.
Make sure that you configure this file with your certificates correctly.
This file will not be modified by our package. One less thing to worry
about on ugprades.
- logrotate script installed by default
Be careful if you done yours by hand. It might conflict with your script.
- New Captive Portal Network Access Detection technique
The previous approach to redirect users to the Internet when access was
enabled never reliably worked so we are introducing a new javascript-based
technique to do so. This approach involves a couple of clever tricks and
some browser-specific adjustments. Please review the differences between
your current html/user/content/templates/release.html file and the new
html/user/content/templates/release.html.rpmnew file. Also the behavior is
adjusted by pf.conf's redirtimer, redirecturl and always_use_redirecturl
parameters under [trapping] and network_detection_ip under [captive_portal].
More about this feature can be found in the Administration guide.
- Apache's automatic performance settings adjustments
Apache's configuration is now adjusted based on total system memory to
prevent swapping scenarios with PacketFence. We feel the dynamic
configuration should do a good job but feel free to maintain your Apache
configuration by hand if you know better.
- packetfence-freeradius2
A new package that configures FreeRADIUS is available now. If you upgrade
DO NOT install it unless you really know what you are doing.
- clean-up in conf/violations.conf
We added better examples and reduced the length of some violation names to
improve user experience especially in the Web Admin. Update your
configuration if you want to benefit from those changes.
- deprecated pf.conf parameters
registration.queuesize was removed.
- User-Agent violations rewrite
If you are using USERAGENT::<id> triggers in your violation configuration,
you need to updated them. We completely changed the back-end and the IDs
are now all different. Check in the Web Admin under configuration ->
user-agent for the new IDs and the new possibilities.
- Important problems found in the port-security for the 3Com Switch 4200G
There is a bug in these switches that make the port-security support in
PacketFence flaky. If you use it you should upgrade to a MAC Auth / 802.1X
configuration.
- Status unknown of the port-security support for the 3Com SuperStack 4500
We had problems with this code with the 4200G and since we don't have
access to a SS4500 we cannot guarantee that it works. Please get in touch
with us if you have a SS4500 and can run some tests for us.
- Behavior change regarding wired MAC-Authentication
No matter what is connected on the port (ie: VoIP), when a client using
MAC-Authentication need to change VLAN, we shut / no shut the port. This
might affect ongoing Voice over IP calls but is better than the previous
behavior were the node was simply left where it was. This is an interim
measure before we implement RADIUS Change of Authorzation support (CoA).
- node lookup changed
By default we do not update the node lookup module in order to allow local
customization. However if you want to benefit from the improved node lookup
script, make sure that you overwrite your existing lib/pf/lookup/node.pm
module with the new file (.rpmnew). Be aware that the output of `pfcmd
lookup node <mac>` changed so make sure you update your parsing scripts (if
any). This also affects the Node lookup section of the Web Admin interface.
----
Upgrading from a version prior to 2.1.0
---------------------------------------
----
- You MUST upgrade conf/templates/httpd.conf and
conf/templates/named_vlan.conf
The location of the PID files changed. The templates must reflect this new
location: var/run/ instead of var/
Also in conf/templates/named_vlan.conf the configuration directory is
var/named instead of var/.
See the .rpmnew files for the proper configuration.
- Module versioning for pf::vlan::custom and pf::radius::custom
We are now relying on module versioning to catch interface changes before
they hurt the users. PacketFence will generate errors on startup if you
have not upgraded your modules' interface and version. The interfaces have
not changed so all you need to do on upgrade is to add:
our $VERSION = 1.00;
to both lib/pf/radius/custom.pm and lib/vlan/custom.pm.
- Default port bounce duration changed
To support a variety of Linux desktop operating systems we needed to
increase the duration of our port bounce from 2 seconds to 5 seconds. On a
very busy setup this could have consequences. Either increase the number of
concurrent threads working (nbtraphandlerthreads under [vlan]) or restore
the port bounce duration to 5 seconds (bounce_duration under [vlan]).
- Several Nortel/Avaya module changes
5520 renamed to 5500, 5520Stacked is no longer necessary, firmware 6.x
support for the 5500 series requires you to use module name BayStack5500_6x.
Just make sure to review your conf/switches.conf so that the config refers
to proper modules.
- Removed conf/templates/*.pl captive portal extensions
This mechanism was removed since the new pf::web::custom mechanism is
cleaner and less error-prone. Make sure to migrate any custom code you have
in release.pl, login.pl, enabler.pl, redirect.pl, scan-in-progress.pl,
error.pl, status.pl and register.pl to lib/pf/web/custom.pm.
- pid files changed location
Previously in var/ they are now in var/run/
- New configuration directory for generated configuration: var/conf/
Changed the location of the generated configuration file from conf/
to var/conf/. This will mitigate the fact that people were trying to
modify the generated files instead of the templates.
- 'pending' node status now relies on javascript to detect network access
The HTML meta refresh approach never reliably worked so there's a new
javascript technique. If you rely on node status 'pending' in your
workflow, please check pf.conf's new captive_portal.network_detection_ip
variable and re-test your portal to make sure it still works.
- Output of node lookup changed (again!)
The output of `pfcmd lookup node <mac>` changed. Make sure you update your
parsing scripts (if any). This also affects the Node lookup section of the
Web Admin interface.
- pf::SNMP (lib/pf/SNMP.pm) API level bump
We changed the contract of setAdminStatus() so we bumped the version of
pf::SNMP to 2.00. If you use setAdminStatus() in custom code make sure you
update your calls.
----
Upgrading from a version prior to 2.0.1
---------------------------------------
----
- lib/pf/vlan.pm's fetchVlanForNode interface changed
If you built a customized version of this method in lib/pf/vlan/custom.pm
you will need to update it.
- Meru Controller 3000 now named Meru Controller
Since our code should work for all Meru Controllers, we renamed the module.
Meru::MC3000 is now Meru::MC. If you upgrade make sure you update your
conf/switches.conf or Configuration -> Switches (in the web admin).
- Output of node lookup changed
The output of `pfcmd lookup node <mac>` changed. Make sure you update your
parsing scripts (if any). This also affects the Node lookup section of the
Web Admin interface.
----
Upgrading from a version prior to 2.0.0
---------------------------------------
----
- Database schema update
Several new fields were added. You need to update your schema with:
mysql -u root -p pf -v < db/upgrade-1.9.0-2.0.0.sql
- FreeRADIUS module rewritten and renamed
The FreeRADIUS has been completely re-written from the previous release
series. Now, except for the authentication against the PacketFence server
all the control is centralized in the PacketFence configuration. No more
customization required in the FreeRADIUS module! We strongly recommend
that you carefully migrate to this module and forget about the old one.
We also changed the name from rlm_perl_packetfence.pl to packetfence.pm so
update your FreeRADIUS configuration accordingly.
- /cgi-bin/pdp.cgi moved
Remote snort probes or other mechanisms relying on the presence of this
file should be updated to be /webapi instead. Upgrading each probe's
packetfence-remote-snort-sensor will take care of this for remote snort
probes. All other custom means should be manually upgraded.
- SOAP handler changed
The URI of the SOAP handler changed from
http://www.packetfence.org/PFEvents to http://www.packetfence.org/PFAPI. To
better reflect the fact that it is not just an event handling server. You
will need to upgrade your remote snort probes with the new PacketFence
remote snort sensor RPM or manually change the URI.
- Output of node lookup changed
The output of `pfcmd lookup node <mac>` changed. Make sure you update your
parsing scripts (if any). This also affects the Node lookup section of the
Web Admin interface.
- pfcmd_vlan output change
Output of `pfcmd_vlan` changed dramatically. If you used scripts to
automate tasks with pfcmd_vlan and expected particular output, your scripts
should be updated.
- pfcmd input and output change
If you used script to automate tasks relying on the `pfcmd` interface, you
need to update them. Output of `pfcmd node`, `pfcmd locationhistorymac`,
`pfcmd locationhistoryswitch`, `pfcmd violation view all`, `pfcmd
switchconfig` and `pfcmd fingerprint view all` also changed.
- DHCP and DNS server configuration changes
With previous versions it was recommended to configure DHCP and DNS servers
manually and instructions were provided to do so on the Administration
Guide. Starting with this version it is recommended to use the configuration
templates and let PacketFence auto-configure the DHCP and DNS servers.
Migrating to this new approach is not mandatory but is recommended. To do so
please follow the "DHCP and DNS Server Configuration (networks.conf)"
section of the Administration Guide.
- lib/pf/vlan.pm interface changed
If you built a customized version of vlan.pm in lib/pf/vlan/custom.pm be
aware that there were a lot of changes. We strongly recommend you rewrite
your custom.pm on top of these new changes instead keeping your old.
- Captive Portal changes
By default pf::web is no longer exporting it's subroutines. This means that
all the captive portal scripts in cgi-bin/ will need to be updated to use
the full name pf::web::web_node_register() instead of web_node_register().
If your cgi-bin files are the default ones you don't need to change
anything. These breaking changes are introduced to allow pf::web::custom to
redefine any subroutine in pf::web and will allow easier upgrade path for
users who need to customize the portal.
- Violation priority enforcement
Violation priorities are now properly enforced: 1 means highest priority
and 10 means lowest priority. Even if documentation said so, before this
release, the code enforced it the other way around. This affects what
violation is shown on multiple violations (it will favor highest) and has
most impact when Nessus scanning is used. Since this is a default behavior
change, you should double check your config!
- External remediation pages
Violations with fully qualified URLs are now handled with new code that
uses mod_proxy and mod_rewrite instead of mod_proxy_html. This was done
because the current implementation is broken out of the box on a CentOS
system without manually compiling and installing the mod_proxy_html
package. If you used it then reverify all your remediation pages with
fully qualified URLs as they might be broken now.
- SMC TS8800M module changes
A lot of changes were made to this SMC module such that problems occuring
with the previous module should be resolved now. These fixes also required
an updated firmware from SMC. Make sure your switch runs at opcode 2.4.5.13
for the SMC TigerStack 8824M or 8848M to work properly with PacketFence.
- loadMACintoDB.pl removed
Dropping loadMACintoDB.pl. Replaced by node import feature see `pfcmd node
import` or Node -> Import in the Web Administration interface.
- connect_and_read.pl and dhcp_dumper moved
They are now located in addons/.