Installing XWiki on FreeBSD

== Introduction ==

This guide takes one through **all** processes of installing XWiki into a FreeBSD environment. This guide has been provisioned to be used in a FreeBSD Jail architecture but easily contributes itself to a normal environment too as the extra **Jail** steps provided are not necessary.

4

5

== Creating the Jail ==

6

7

The first thing we need to do in order to get **XWiki** up and running is create the **jail** that the software will reside in. First of all I'm going to position this **jail** in my **ZFS** pool and call it **wiki** and then I will start on the **jail** creation itself:

8

9

10

Test-BSD# mkdir /zfs/jail/wiki

11

Test-BSD# setenv D /zfs/jail/wiki

12

Test-BSD# mkdir -p $D

13

Test-BSD# make installworld DESTDIR=$D

14

Test-BSD# make distribution DESTDIR=$D

15

Test-BSD# mount -t devfs devfs $D/dev

16

17

18

Once the jail has been created we can now add it to the ##/etc/rc.conf## file:

19

20

21

ifconfig_de0_alias1="inet 192.168.0.151 netmask 255.255.255.0"

22

jail_list="dns wiki"

23

jail_wiki_rootdir="/zfs/jail/wiki"

24

jail_wiki_hostname="wiki.yourdomain.net"

25

jail_wiki_interface="de0"

26

jail_wiki_ip="192.168.0.151"

27

jail_wiki_devfs_enable="YES"

28

29

30

and then start the newly built and configured **jail**:

31

32

33

Test-BSD# /etc/rc.d/jail start wiki

34

Configuring jails:.

35

Starting jails: wiki.yourdomain.net.

36

37

38

From there we can test to see if it has been successfully activated:

Test-BSD# jls

JID IP Address Hostname Path

43

1 192.168.0.149 ns1.yourdomain.net /zfs/jail/dns

44

2 192.168.0.151 wiki.yourdomain.net /zfs/jail/wiki

45

46

47

and now mount the **ports** collection inside it:

Test-BSD# sh

# D=/zfs/jail/wiki

# mkdir -p $D/usr/ports

53

# mount_nullfs /usr/ports $D/usr/ports

54

# mount | sort

55

/dev/ad0s1a on / (ufs, local)

56

/usr/ports on /zfs/jail/wiki/usr/ports (nullfs, local)

57

ZPOOL_1 on /zfs (zfs, local)

58

devfs on /dev (devfs, local, multilabel)

59

devfs on /zfs/jail/dns/dev (devfs, local, multilabel)

60

devfs on /zfs/jail/wiki/dev (devfs, local, multilabel)

61

62

63

From here we can login to the **jail** and build the applications we need starting with the **Nano** text editor:

64

65

66

Test-BSD# jexec 2 tcsh

67

wiki# cd /usr/ports/*/nano

68

wiki# make install clean

69

70

71

The next task is to setup the ##/etc/rc.conf##, ##/etc/hosts##, and ##/etc/resolv.conf## files within the jail, while taking some prerequisites into consideration:

72

73

74

wiki#cat /etc/rc.conf

75

defaultrouter="192.168.0.254"

76

hostname="wiki.yourdomain.net"

77

tomcat60_enable="YES"

78

postgresql_enable="YES"

79

postgresql_user="root"

80

jail_sysvipc_allow="YES"

wiki#cat /etc/hosts

# $FreeBSD: src/etc/hosts,v 1.16.34.1.2.1 2009/10/25 01:10:29 kensmith Exp $

#

# Host Database

#

# This file should contain the addresses and aliases for local hosts that

90

# share this file. Replace 'my.domain' below with the domainname of your

91

# machine.

92

#

93

# In the presence of the domain name service or NIS, this file may

94

# not be consulted at all; see /etc/nsswitch.conf for the resolution order.

95

#

96

#

97

::1 localhost localhost.my.domain

98

127.0.0.1 localhost localhost.my.domain

99

#

100

# Imaginary network.

101

#10.0.0.2 myname.my.domain myname

102

#10.0.0.3 myfriend.my.domain myfriend

103

#

104

# According to RFC 1918, you can use the following IP networks for

105

# private nets which will never be connected to the Internet:

106

#

107

# 10.0.0.0 - 10.255.255.255

108

# 172.16.0.0 - 172.31.255.255

109

# 192.168.0.0 - 192.168.255.255

110

#

111

# In case you want to be able to connect to the Internet, you need

112

# real official assigned numbers. Do not try to invent your own network

113

# numbers but instead get one from your network provider (if any) or

114

# from your regional registry (ARIN, APNIC, LACNIC, RIPE NCC, or AfriNIC.)

115

#

116

117

192.168.0.151 wiki.yourdomain.net wiki

118

192.168.0.151 wiki.yourdomain.net.

wiki# cat /etc/resolv.conf

124

nameserver 192.168.0.149

125

126

127

Now that the jail internals have been setup, it is time to start adding the software needed to run **XWiki**.

128

129

== Apache Tomcat Installation ==

130

131

The installation of **Tomcat** will be version 6 built from the **ports** repository.

132

133

134

wiki# cd /usr/ports/*/tomcat6

135

wiki# make install clean

136

137

138

If all went to plan there should be an error message at the tail end of the install:

139

140

141

Please open http://java.sun.com/javase/downloads/index.jsp

142

in a web browser and follow the "Download" link for

143

"JDK US DST Timezone Update Tool - 1_3_18" to obtain the

144

time zone update file, tzupdater-1_3_18-2009k.zip.

145

146

Please download the patchset, bsd-jdk16-patches-4.tar.bz2, from

147

http://www.eyesbeyond.com/freebsddom/java/jdk16.html.

148

149

Please place the downloaded file(s) in /usr/ports/distfiles

150

and restart the build.

*** Error code 1

Stop in /usr/ports/java/jdk16.

155

*** Error code 1

156

157

Stop in /usr/ports/java/jdk16.

158

*** Error code 1

159

160

Stop in /usr/ports/www/tomcat6.

161

162

163

This basically tells us that we need to install the **JDK US DST Timezone Update Tool** and also the **JDK16** environment in order to proceed. Since both these packages have license agreements they cannot be downloaded directly using a utility such as ##wget##, so one has to actually open up a browser in order to navigate to the links, accept the license agreements and download the packages.

164

165

[[[[image:web-timezone.png]]>>attach:timezone.png||rel="__blank"]]

166

167

For the **JDK US DST Timezone Update Tool** go [[here>>http://java.sun.com/javase/downloads/index.jsp]] and for the **JDK16** go [[here>>http://http://www.freebsdfoundation.org/cgi-bin/download?download=diablo-jdk-freebsd7.i386.1.6.0.07.02.tbz]] although depending on how new the **port** is, it may complain and ask for a different set of downloads.

168

169

Once downloaded, upload the files to the server using ##ftp##, ##sftp##, ##scp##, ##rsync##, or another method then move the files into the ##ports## directory:

170

171

172

scp tzupdater-1_3_31-2010i.zip [email protected]:/usr/home/mark/

173

scp diablo-jdk-freebsd7.i386.1.6.0.07.02.tbz [email protected]:/usr/home/mark/

174

ssh [email protected]

175

$ su -

176

Test-BSD# cd /usr/home/mark

177

Test-BSD# mv diablo-jdk-freebsd7.i386.1.6.0.07.02.tbz /usr/ports/distfiles/

178

Test-BSD# mv tzupdater-1_3_31-2010i.zip /usr/ports/distfiles/

179

180

181

From there we need to login to the jail again and build the **JDK** port:

182

183

184

wiki# cd /usr/ports/java/diablo-jdk16/

185

wiki# make install clean

186

187

188

Again the system may blow up and come up with an error meaning that the directions on screen need to be followed:

189

190

191

Because of licensing restrictions, you must fetch the distribution

manually.

Please access

http://www.FreeBSDFoundation.org/cgi-bin/download?download=diablo-caffe-freebsd7-amd64-1.6.0_07-b02.tar.bz2

197

198

with a web browser and "Accept" the End User License Agreement for

199

"Caffe Diablo 1.6.0".

200

201

Please open http://java.sun.com/javase/downloads/index.jsp

202

in a web browser and follow the "Download" link for

203

"JDK US DST Timezone Update Tool - 1_3_18" to obtain the

204

time zone update file, tzupdater-1_3_18-2009k.zip.

205

206

Please place the downloaded file(s) in /usr/ports/distfiles.

*** Error code 1

Stop in /usr/ports/java/diablo-jdk16.

211

*** Error code 1

212

213

Stop in /usr/ports/java/diablo-jdk16.

214

215

216

Once downloaded again ##scp## or other method can be used to upload the package to the server:

217

218

219

scp diablo-caffe-freebsd7-amd64-1.6.0_07-b02.tar.bz2 [email protected]:/usr/home/mark/

220

ssh [email protected]

221

$ su -

222

Test-BSD# cd /usr/home/mark

223

Test-BSD# mv diablo-caffe-freebsd7-amd64-1.6.0_07-b02.tar.bz2 /usr/ports/distfiles/

224

225

wiki# cd /usr/ports/java/diablo-jdk16/

226

wiki# make install clean

227

228

229

If the system starts complaining about the //JDK US DST Timezone Update Tool// it means that either the older version needs to be found or alternatively a **port** upgrade must be performed. Of course an easier way would be to just turn it off altogether however we will proceed as per the dialogs.

230

231

Since an older version of the //JDK US DST Timezone Update Tool// isn't available and the port upgrade didn't manage to solve the problem either, even after having a production build with the same packages the best way to proceed at this point was to disable the tool.

232

233

234

# cd /usr/ports/java/jdk16

# make config

Then **unselect** ##tzupdate## and press **OK**. After another attempt at building the **JDK** environment the system again complains with this error:

239

240

241

wiki# make install clean

242

===> Vulnerability check disabled, database not found

243

===> Found saved configuration for jdk-1.6.0.3p4_12

244

245

IMPORTANT: To build the JDK 1.6.0 port, you should have at least

246

2.5Gb of free disk space in the build area!

247

248

249

Due to licensing restrictions, certain files must be fetched manually.

250

251

Please download the Update 3 Source from

252

http://www.java.net/download/jdk6/6u3/promoted/b05/jdk-6u3-fcs-src-b05-jrl-24_sep_2007.jar

253

and the Source Binaries from

254

http://www.java.net/download/jdk6/6u3/promoted/b05/jdk-6u3-fcs-bin-b05-jrl-24_sep_2007.jar

255

and the Mozilla Headers from

256

http://www.java.net/download/jdk6/6u3/promoted/b05/jdk-6u3-fcs-mozilla_headers-b05-unix-24_sep_2007.jar

257

.

258

259

Please download the patchset, bsd-jdk16-patches-4.tar.bz2, from

260

http://www.eyesbeyond.com/freebsddom/java/jdk16.html.

261

262

Please place the downloaded file(s) in /usr/ports/distfiles

263

and restart the build.

*** Error code 1

Stop in /usr/ports/java/jdk16.

268

*** Error code 1

269

270

Stop in /usr/ports/java/jdk16.

271

272

273

Meaning that we need to fetch each and every one of those components and drop them into the **/usr/ports/distfiles** directory. A trick however is to use the **wget** tool in the directory itself meaning that no other work needs to be done:

274

275

276

wget http://www.java.net/download/jdk6/6u3/promoted/b05/jdk-6u3-fcs-src-b05-jrl-24_sep_2007.jar

277

278

wget http://www.java.net/download/jdk6/6u3/promoted/b05/jdk-6u3-fcs-bin-b05-jrl-24_sep_2007.jar

279

280

wget http://www.java.net/download/jdk6/6u3/promoted/b05/jdk-6u3-fcs-mozilla_headers-b05-unix-24_sep_2007.jar

281

282

283

Once all that is done and finished we can run the ##make install clean## command again from within the **JDK port**. If there are any more errors that pop-up just follow the on-screen instructions in order to overcome them. The majority of the errors will be to build **Java** components without the **tzupdate** enabled.

284

285

And finally install **Tomcat6** into the system:

286

287

288

wiki# cd /usr/ports/*/tomcat6

289

wiki# make install clean

== Postgresql ==

The next stage in getting the XWiki system up and running is to install the **Postgresql** database backend. Many different types of databases are compatible with **XWiki**, however for **FreeBSD** the **Postgresql** is the only database that has been functional and able to be tested.

295

296

So now let's start by installing both **server** and **client** components; the version that is going to be installed is: **8.2.17_1**. This is a simple procedure that will be done from the **ports** collection.

297

298

299

wiki# cd /usr/ports/databases/postgresql82-client

300

wiki# make install clean

301

wiki# cd ../postgresql82-server

302

wiki# make install clean

303

304

305

Now it's a good idea to restart the **jail**:

306

307

308

Test-BSD# /etc/rc.d/jail restart wiki**

and login again:

Test-BSD# jls

JID IP Address Hostname Path

316

1 192.168.0.149 ns1.yourdomain.net /zfs/jail/dns

317

4 192.168.0.151 wiki.yourdomain.net /zfs/jail/wiki

318

Test-BSD# jexec 4 tcsh

319

320

321

From here create the **database cluster**:

wiki# su pgsql

$ /usr/local/bin/initdb /usr/local/pgsql/data

326

The files belonging to this database system will be owned by user "pgsql".

327

This user must also own the server process.

328

329

The database cluster will be initialized with locale C.

330

331

creating directory /usr/local/pgsql/data ... ok

332

creating subdirectories ... ok

333

selecting default max_connections ... 10

334

selecting default shared_buffers/max_fsm_pages ... 400kB/20000

335

creating configuration files ... ok

336

creating template1 database in /usr/local/pgsql/data/base/1 ... FATAL: could not create shared memory segment: Function not implemented

337

DETAIL: Failed system call was shmget(key=1, size=1818624, 03600).

338

child process exited with exit code 1

339

initdb: removing data directory "/usr/local/pgsql/data"

340

341

342

As can be seen there is an error which is specifically caused by running **PostgreSQL** in a **jail** environment. This can be overcome by adding: ##jail_sysvipc_allow="YES"## to the ##/etc/rc.conf## file in the base install and re-running the PostgreSQL initialization:

wiki# su pgsql

$ /usr/local/bin/initdb /usr/local/pgsql/data

347

The files belonging to this database system will be owned by user "pgsql".

348

This user must also own the server process.

349

350

The database cluster will be initialized with locale C.

351

352

creating directory /usr/local/pgsql/data ... ok

353

creating subdirectories ... ok

354

selecting default max_connections ... 40

355

selecting default shared_buffers/max_fsm_pages ... 28MB/179200

356

creating configuration files ... ok

357

creating template1 database in /usr/local/pgsql/data/base/1 ... ok

358

initializing pg_authid ... ok

359

initializing dependencies ... ok

360

creating system views ... ok

361

loading system objects' descriptions ... ok

362

creating conversions ... ok

363

setting privileges on built-in objects ... ok

364

creating information schema ... ok

365

vacuuming database template1 ... ok

366

copying template1 to template0 ... ok

367

copying template1 to postgres ... ok

368

369

WARNING: enabling "trust" authentication for local connections

370

You can change this by editing pg_hba.conf or using the -A option the

371

next time you run initdb.

372

373

Success. You can now start the database server using:

374

375

/usr/local/bin/postgres -D /usr/local/pgsql/data

376

or

377

/usr/local/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start

378

379

380

Now let's start the **Postgresql** service:

wiki# su - pgsql

$ /usr/local/bin/postgres -D /usr/local/pgsql/data

385

386

387

The process can be further tested using the: ##ps -aux | grep postgres## command. Now that the service is up and running we can go on to creating the **XWiki user and database**:

388

389

390

$ createuser xwiki -S -D -R -P -Upgsql

391

Enter password for new role:

Enter it again:

CREATE ROLE

$ createdb xwiki -Eunicode -Oxwiki -Upgsql

CREATE DATABASE

From here the final stage in **PostgreSQL configuration** is to add a line trusting the interface in the ##/usr/local/pgsql/data/pg_hba.conf## file so that the bottom of the file looks like this:

400

401

402

# TYPE DATABASE USER CIDR-ADDRESS METHOD

403

404

# "local" is for Unix domain socket connections only

405

local all all trust

406

# IPv4 local connections:

407

host all all 127.0.0.1/32 trust

408

# IPv6 local connections:

409

host all all ::1/128 trust

410

411

host all all 192.168.0.151/32 trust

412

413

414

All that is needed to be done now is the **Postgresql** service restarted and for security the database can even be listed to ensure it's creation:

415

416

417

wiki# /usr/local/etc/rc.d/postgresql restart

$ su -

Password:

Test-BSD# jls

JID IP Address Hostname Path

425

1 192.168.0.149 ns1.yourdomain.net /zfs/jail/dns

426

2 192.168.0.151 wiki.yourdomain.net /zfs/jail/wiki

427

Test-BSD# jexec 2 tcsh

wiki# su - pgsql

$ psql -l

List of databases

Name | Owner | Encoding

432

-----------+-------+-----------

433

postgres | pgsql | SQL_ASCII

434

template0 | pgsql | SQL_ASCII

435

template1 | pgsql | SQL_ASCII

xwiki | xwiki | UTF8

(4 rows)

== Installing XWiki ==

441

442

To start with let's download the **XWiki war** file:

443

444

445

wiki# wget http://download.forge.objectweb.org/xwiki/xwiki-enterprise-web-3.5.1.war

446

--2010-09-11 20:56:48-- http://download.forge.objectweb.org/xwiki/xwiki-enterprise-web-3.5.1.war

447

Resolving download.forge.objectweb.org... 88.191.79.12, 2a01:e0b:1:79:2e0:f4ff:fe1b:b525

448

Connecting to download.forge.objectweb.org|88.191.79.12|:80... connected.

449

HTTP request sent, awaiting response... 200 OK

450

Length: 141657140 (135M) [text/plain]

451

Saving to: `xwiki-enterprise-web-3.5.1.war'

452

453

100%[======================================>] 141,657,140 406K/s in 5m 48s

454

455

2010-09-11 21:02:36 (406 KB/s) - `xwiki-enterprise-web-3.5.1.war' saved [141657140/141657140]

456

457

458

This will now get renamed to ##xwiki.war## and moved to the ##$TOMCAT_HOME/webapps## directory:

459

460

461

wiki# mv xwiki-enterprise-web-3.5.1.war xwiki.war

462

wiki# mv xwiki.war /usr/local/apache-tomcat-6.0/webapps/

463

464

465

From this moment we can start **Tomcat6** and look at the **WAR** file extracting into the ##webapps## directory:

466

467

468

wiki# ls /usr/local/apache-tomcat-6.0/webapps

469

ROOT examples manager

470

docs host-manager xwiki.war

471

wiki# /usr/local/etc/rc.d/tomcat6 restart

472

tomcat60 not running? (check /var/run/tomcat60.pid).

473

Starting tomcat60.

474

wiki# ls /usr/local/apache-tomcat-6.0/webapps

475

ROOT examples manager xwiki.war

476

docs host-manager xwiki

477

478

479

=== Configuring the database connection ===

480

481

We must install the **JDBC connector for PostgreSQL** into XWiki:

482

483

484

wiki# cd /usr/local/apache-tomcat-6.0/webapps/xwiki/WEB-INF/lib

485

wiki# wget http://jdbc.postgresql.org/download/postgresql-8.3-606.jdbc4.jar

486

--2010-09-11 21:11:19-- http://jdbc.postgresql.org/download/postgresql-8.3-606.jdbc4.jar

487

Resolving jdbc.postgresql.org... 200.46.204.71

488

Connecting to jdbc.postgresql.org|200.46.204.71|:80... connected.

489

HTTP request sent, awaiting response... 200 OK

490

Length: 476213 (465K) [application/octet-stream]

491

Saving to: `postgresql-8.3-606.jdbc4.jar'

492

493

100%[======================================>] 476,213 151K/s in 3.1s

494

495

2010-09-11 21:11:24 (151 KB/s) - `postgresql-8.3-606.jdbc4.jar' saved [476213/476213]

496

497

498

Edit the ##WEB-INF/hibernate.cfg.xml## file and comment out there rest of the config that doesn't apply:

499

500

501

<!-- Configuration for the default database.

502

Comment out this section and uncomment other sections below if you want to use another database.

503

Note that the database tables will be created automatically if they don't already exist.

504

-->

505

<!--

506

<property name="connection.url">jdbc:hsqldb:file:database/xwiki_db;shutdown=true</property>

507

508

509

<property name="connection.driver_class">org.hsqldb.jdbcDriver</property>

510

<property name="dialect">org.hibernate.dialect.HSQLDialect</property>

511

<property name="connection.provider_class">com.xpn.xwiki.store.DBCPConnectionProvider</property>

-->

...

<!-- PostgreSQL configuration.

522

Uncomment if you want to use PostgreSQL and comment out other database configurations. -->

523

<property name="connection.url">jdbc:postgresql://localhost:5432/xwiki</property>

524

<property name="connection.username">xwiki</property>

525

<property name="connection.password">xwiki</property>

526

<property name="connection.driver_class">org.postgresql.Driver</property>

527

<property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>

528

<property name="connection.provider_class">com.xpn.xwiki.store.DBCPConnectionProvider</property>

529

530

531

<property name="jdbc.use_streams_for_binary">false</property>

...

Restart **Tomcat** again:

540

541

542

wiki# /usr/local/etc/rc.d/tomcat6 restart

543

Stopping tomcat60.

544

Waiting (max 10 secs) for PIDS: 7591, 7591.

Starting tomcat60.

Point the web browser to the URL: ##http:/~/wiki.yourdomain.net:8180/xwiki## at this point and the page should appear!!

549

550

If for some reason an error is given in the browser:

551

552

[[[[image:web-Error.png]]>>attach:Error.png||rel="__blank"]]

553

554

then add this to the: **/usr/local/apache-tomcat-6.0/conf/catalina.policy** file:

555

556

557

grant codeBase "file:${catalina.base}/webapps/xwiki/-" {

558

permission java.security.AllPermission;

559

permission java.io.FilePermission "${catalina.base}/webapps/xwiki/-", "read,write,delete";

560

permission java.io.FilePermission "/var/log/tomcat60/-", "read,write";

561

permission java.io.FilePermission "/WEB-INF/xwiki.cfg", "read";

562

permission java.io.FilePermission "/WEB-INF/hibernate.cfg.xml", "read";

563

permission java.lang.reflect.ReflectPermission "suppressAccessChecks";

564

permission java.util.PropertyPermission "user.name", "read";

565

permission java.util.PropertyPermission "office.*", "read";

566

permission java.util.PropertyPermission "file.encoding", "read";

567

permission java.util.PropertyPermission "org.apache.commons.logging.LogFactory.HashtableImpl", "read";

568

permission java.util.PropertyPermission "org.quartz.properties", "read";

569

permission java.util.PropertyPermission "ANTLR_DO_NOT_EXIT", "read";

570

permission java.util.PropertyPermission "ANTLR_USE_DIRECT_CLASS_LOADING", "read";

571

permission java.util.PropertyPermission "org.apache.xerces.xni.parser.XMLParserConfiguration", "read";

572

permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";

573

permission java.lang.reflect.ReflectPermission "suppressAccessChecks";

574

permission java.lang.RuntimePermission "getClassLoader";

575

permission java.lang.RuntimePermission "createClassLoader";

576

permission java.lang.RuntimePermission "setContextClassLoader";

577

permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina";

578

permission java.lang.RuntimePermission "accessDeclaredMembers";

579

permission java.lang.RuntimePermission "getenv.ProgramFiles";

580

permission java.lang.RuntimePermission "getenv.APPDATA";

};

If still getting errors after this then update the ports tree until the **Tomcat** and **Postgresql** versions are the latest up-to-date ones.

585

586

Once XWiki is up and running the initial screen should look like this:

587

588

[[[[image:web-Wiki-Startup.png]]>>attach:Wiki-Startup.png||rel="__blank"]]

589

590

== Initial Configuration ==

591

592

As claimed by XWiki it currently doesn't have any **pages** or **templates**, meaning that we manually have to do this. Access the Administration section of the **XWiki** interface:

593

594

[[image:web-Xwiki-Admin.png]]

595

596

Then download the XWiki template from [[http://download.forge.objectweb.org/xwiki/xwiki-enterprise-ui-all-3.5.1.xar]], and upload them into the **XWiki** instance:

597

598

[[image:web-Template.png]]

599

600

After the **xar** file has been selected from a folder in your computer click the **Upload** button:

601

602

[[image:web-Template2.png]]

603

604

Click the link on the **xar** file itself to reveal the package contents and click on **Import**:

605

606

[[image:web-Template3.png]]

607

608

The screen will finally display confirmation that the **templates** have been loaded into the **XWiki** instance and that it is time to login:

609

610

[[image:web-Template4.png]]

611

612

Finally go back to the **XWiki** homepage and test that everything has been loaded as planned:

613

614

[[image:web-Full-Wiki.png]]

615

616

Then login as the **Administrator**:

617

618

[[image:web-Full-Wiki-login.png]]

619

620

And begin customizing your new install of **XWiki**:

621

622

[[image:web-Full-Wiki-login2.png]]

== Memory Errors ==

If one experiences random timeouts while attempting to connect to the URL of XWiki, the solution can usually be found within the Tomcat log file.

627

628

First login to the system or Jail environment and go to ##/usr/local/apache-tomcat-6.0/logs##. From there open ##stdout.log## and either pipe to 'tail' to get the end of the file or grep to 'space':

629

630

631

cat stidout.log | tail

632

633

cat stdout.log | grep space

634

635

636

What will eventually be returned among other things should be the lines:

637

638

639

java.lang.OutOfMemoryError: Java heap space

640

Exception in thread "http-8180-Acceptor-0" java.lang.OutOfMemoryError: Java heap space

641

642

643

The error mainly should be contained as **Java heap space** however, it could also come up as **Java perm space**.

644

645

In order to elleviate the issue add:

646

647

648

tomcat60_java_opts="-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server -Xms3072m -Xmx3072m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m -XX:+DisableExplicitGC"

649

650

651

to ##/etc/rc.conf##, where the ##-Xms## and ##-Xmx## values should be set in accordance with what is needed as setting too high could cause Java to use up the system Swap space, thus causing instability inside the OS environment.

652

653

To test if the Java service is online or not one can use the **netstat** and **sockstat** commands:

654

655

656

www# netstat -ap tcp | grep 8180

657

tcp4 0 0 www.8180 *.* LISTEN

658

659

www# sockstat | grep java

660

www java 51547 33 tcp4 192.168.1.170:8180 *:*

661

www java 51547 40 tcp4 192.168.1.170:8009 *:*

662

www java 51547 42 tcp4 192.168.1.170:8005 *:*

663

www java 51547 48 tcp4 192.168.1.170:25739 192.168.1.170:5432

664

www java 51547 302 tcp4 192.168.1.170:56498 192.168.1.170:5432

665

www java 51547 304 stream(not connected)

666

www java 51547 307 tcp4 192.168.1.170:39540 192.168.1.170:5432

667

668

669

If for some reason the process has exited and both ##stderr.log## and ##stdout.log## don't show any valid means of //'why?'//. An answer could be that the system has run out of memory and so some intelligence needs to be built in, in order to detect the Java process not being online.

670

671

It is also a wise idea to check ##/var/log/messages## for any errors or 'unhandled exceptions'.

672

673

Another method would be to check the //root// user mail or/and get emailed an output of the systems logs daily. This can lead to detecting messages such as this:

674

675

676

+pid 21242 (java), uid 80, was killed: out of swap space

677

678

679

A failsafe however, can be built into the system to prevent 'downtime';

680

681

{{info}}Ideal for a home server environment but for enterprise scale more memory would need to be purchased!{{/info}}

682

683

The script below will detect if Tomcat stops running and restart the process automatically:

684

685

686

#!/usr/local/bin/bash

687

688

export PATH=/bin:/usr/bin:/sbin:/usr/sbin:/usr/local/bin:/usr/local/sbin

689

#set -v -x

690

691

ntstat=`netstat -ap tcp | grep 8180 | sed -n '1p'`

692

port="8180"

693

694

sock=`sockstat | grep java`

sock_name="java"

#echo $ntstat

#echo $port

if [[ $sock =~ $sock_name ]]; then

701

echo "Output of Sockstat command" > /root/java_restart/java_restart.log;

702