Official Kali Linux Mirrors

Using Official Repositories

The Kali Linux distribution has two repositories, which are mirrored world-wide:

• http.kali.org (mirrorlist): the main package repository;
• cdimage.kali.org (mirrorlist): the repository of pre-built Kali ISO images.

When using the default hosts listed above, you’ll automatically be redirected to a mirror site which is geographically close to you, and which is guaranteed to be up-to-date. If you prefer to manually select a mirror, click on the mirrorlist link near each hostname above and select a mirror that suits you. You will then need to edit your /etc/apt/sources.list file accordingly with the chosen values.

IMPORTANT! Do not add additional repositories to your /etc/apt/sources.list file.Doing so will most likely break your Kali installation.

How to Set Up a Kali Linux Mirror

Requirements

To be an official Kali Linux mirror, you will need a web-accessible server (http required and https if possible too) with lots of disk space, good bandwidth, rsync, and SSH access enabled. As of early 2015, the main package repository is about 450 GB and the ISO images repository is about 50 GB but you can expect those numbers to grow regularly. A mirror site is expected to make the files available over HTTP and RSYNC so those services will need to be enabled. FTP access is optional.

Note on “Push Mirroring” — The Kali Linux mirroring infrastructure uses SSH-based triggers to ping the mirrors when they need to be refreshed. This currently takes place 4 times a day.

Create a User Account for the Mirror

If you don’t have yet an account dedicated for the mirrors, create such an account (here we call it “archvsync”):

$ sudo adduser –disabled-password archvsync
Adding user ‘archvsync’ …
[…]
Is the information correct? [Y/n]

Create Directories for the Mirror

Create the directories that will contain the mirrors and change their owner to the dedicated user that you just created:

$ sudo mkdir /srv/mirrors/kali{,-images}
$ sudo chown archvsync:archvsync /srv/mirrors/kali{,-images}

Configure rsync

Next, configure the rsync daemon (enable it if needed) to export those directories:

$ sudo sed -i -e “s/RSYNC_ENABLE=false/RSYNC_ENABLE=true/” /etc/default/rsync
$ sudo vim /etc/rsyncd.conf
$ cat /etc/rsyncd.conf
uid = nobody
gid = nogroup
max connections = 25
socket options = SO_KEEPALIVE

[kali]
path = /srv/mirrors/kali
comment = The Kali Archive
read only = true

[kali-images]
path = /srv/mirrors/kali-images
comment = The Kali ISO images
read only = true
$ sudo service rsync start
Starting rsync daemon: rsync.

Configure Your Mirror

Configuration of your web server and FTP server are outside the scope of this article. Ideally, you should export the mirrors at http://yourmirror.net/kali and http://yourmirror.net/kali-images (and do the same for the FTP protocol, if you’re supporting it).

Now comes interesting part: the configuration of the dedicated user that will handle the SSH trigger and the actual mirroring. You should first unpack ftpsync.tar.gz in the user’s account:

$ sudo su – archvsync
$ wget http://archive.kali.org/ftpsync.tar.gz
$ tar zxf ftpsync.tar.gz

Now we need to create a configuration file. We start from a template and we edit at least the MIRRORNAME, TO, RSYNC_PATH, and RSYNC_HOST parameters:

$ cp etc/ftpsync.conf.sample etc/ftpsync-kali.conf
$ vim etc/ftpsync-kali.conf
$ grep -E ‘^[^#]’ etc/ftpsync-kali.conf
MIRRORNAME=`hostname -f`
TO=“/srv/mirrors/kali/”
RSYNC_PATH=“kali”
RSYNC_HOST=archive.kali.org

Set Up the SSH Keys

The last step is to setup the .ssh/authorized_keys file so that archive.kali.org can trigger your mirror:

$ mkdir -p .ssh
$ wget -O – -q http://archive.kali.org/pushmirror.pub >>.ssh/authorized_keys

If you have not unpacked the ftpsync.tar.gz in the home directory, then you must adjust accordingly the “~/bin/ftpsync” path, which is hard-coded in .ssh/authorized_keys.

Now you must send an email to devel@kali.org with all the URLs of your mirrors so that you can be added in the main mirror list and to open up your rsync access on archive.kali.org. Please indicate clearly who should be contacted in case of problems (or if changes must be made/coordinated to the mirror setup).

Instead of waiting for the first push from archive.kali.org, you should run an initial rsync with a mirror close to you, using the mirror list linked above to select one. Assuming that you picked archive-4.kali.org, here’s what you can run as your dedicated mirror user:

$ rsync -qaH archive-4.kali.org::kali /srv/mirrors/kali/ &
$ rsync -qaH archive-4.kali.org::kali-images /srv/mirrors/kali-images/ &

Set Up cron to Manually Mirror ISO Images

The ISO images repository does not use push mirroring so you must schedule a daily rsync run. We provide a bin/mirror-kali-images script, which is ready to use that you can add in the crontab of your dedicated user. You just have to configure etc/mirror-kali-images.conf.

$ sudo su – archvsync
$ cp etc/mirror-kali-images.conf.sample etc/mirror-kali-images.conf
$ vim etc/mirror-kali-images.conf
$ grep -E ‘^[^#]’ etc/mirror-kali-images.conf
TO=/srv/mirrors/kali-images/
$ crontab -e
$ crontab -l
# m h dom mon dow command
39 3 * * * ~/bin/mirror-kali-images

Please adjust the precise time so that archive.kali.org doesn’t get overloaded by too many mirrors at the same time.

Official Kali Linux Sites

The Kali Linux project uses several different subdomains of kali.org, each with a specific purpose. This article lists the official Kali sites and the purpose each one of them serves. Note that these sites are the only official Kali Linux sites and are the only authoritative sources of information available for the distribution.

The sites listed below are the ONLY official outlets for the Kali Linux Distribution.

Public Websites

• www.kali.org
• docs.kali.org
• forums.kali.org
• bugs.kali.org
• git.kali.org
• tools.kali.org
• pkg.kali.org

The main Kali Linux website is our primary means of communicating news about the Kali Linux project, general introductory information, and general updates about the project and its ongoing development.
Blog posts about new tools, features, Kali Linux tips, tricks, and tutorials can be found here. This should be your one and only sourceto download the official Kali Linux distribution.

Kali Linux IRC Channel

Kali Linux has an official IRC channel, #kali-linux, on the Freenode network. Please take a few moments to review the rules and guidelines below before joining the channel.

#kali-linux IRC Rules and Guidelines

We try to remain as informal as possible but there are some rules and we’d appreciate if you would follow them! Broadly, if you’re friendly, tolerant, and reasonable, you’ll probably go a long way without any specific knowledge of the rules – but for to avoid any doubt and prevent any misunderstandings, here they are.

How to Treat Other Users

In order to make the channel a pleasant place for all of our users, we expect all to remain as friendly and tolerant as possible. We request that you refrain from profanity and that you show respect to the other channel members and visitors. If you find that you’re becoming frustrated with the channel or other users, we encourage you to take a moment to do something else. Try to ensure you don’t make people feel like you’re just taking advantage of them – help others out while you’re waiting for a reply to your questions, and say thanks!

How to Argue

As mentioned above, we’d appreciate it if you’d strive to be friendly and tolerant. We also encourage debates and in-depth discussions about topical subjects. If you choose to participate in one, we expect you to remain as reasonable as possible and employ the skills of logic and critical thinking. These skills will serve you well in discussion, enable you to communicate more efficiently, and spot when others are being less than forthcoming with the truth!

Language

Our IRC channel is an English-speaking channel. There are no other official channels in any other language.

We are a family-friendly IRC channel and will not tolerate foul language. Save it for the playground.

Staying on Topic

We maintain no strict policy regarding off-topic chat in the channel however, the discussion of Kali Linux projects is the primary focus of the channel, so you may be asked to take discussions elsewhere, particularly if there are venues on freenode better suited to them (such as #politics), if there are other more relevant conversations going on, or if they’re repetitive or otherwise seen by the channel staff as being detrimental to the good atmosphere of the channel.

Certain things are seen as being specifically off-topic. These topics include:

• Support or encouragement of illegal activity – it should go without saying, but we don’t exist to help you break the law or do things you shouldn’t be doing. Such queries are absolutely off-topic for the channel, for freenode as a whole, and may very well get you removed from the channel and/or network. Please don’t ask. Laws vary from country to country and channel OPs may determine whether a specific discussion is appropriate for the channel or not.
• Warez/cracks/pirated software – these too are off-topic for the channel and network so again: please don’t ask.
• Political and religious matters — Many people have very strong political/religious beliefs and we respect that. We also recognize that these are volatile and contentious topics which have nothing to do with Kali Linux, penetration testing, or anything related to those subjects, and are best discussed elsewhere.

Asking for Help

If you’re asking for help, first off, thanks! – questions and the resulting discussion of the answer(s) in a collaborative environment are what make IRC great and by helping to add to the atmosphere, you benefit the entire Kali Linux community.

We often find that we learn a lot even from questions we already think we know the answers to – about people, alternative approaches, and cool new resources and tools. However, if you are intending to ask a question, we’d appreciate it if you’d follow a couple useful guidelines to help you, and us, make the best use of our time.

• Do your research first — It’s very frustrating when people ask a question that can virtually be answered by punching the keywords into a Google search! We also have forums and a wiki that contain answers to many questions we see daily so it’s to everyone’s benefit if these assets are used before asking in IRC.
• Give us the whole picture — If you’re asked for more information, please provide it accurately. The correct answer will depend on it. Looking at this from another angle: the more we learn about your problem, the more this independently benefits us too – a large part of the development of new releases comes out of helping others with issues discovered with specific setups; even if you’re asking us questions, you can help teach us something too!
• If you find the answer somewhere else, tell us – it isn’t compulsory, but if you don’t get an answer to your question in the channel but you find it elsewhere, consider letting us know! That way, we can help out the next person with a similar question. It also lets people know that you already have an answer you’re happy with, or that if anyone’s researching the question for you, they can stop.
• Wait for an answer – not everyone in the channel is online all the time, and you may find you get an answer several minutes, or even hours, later. Feel free to stick around and chat, or even answer other peoples questions – you’ll find it helps pass the time and makes others likely to help you! Help us build a community of friendly security professionals and enthusiasts.

Spam, Flooding, and Various Other Forms of Disruptive Behaviour

Spam, flooding, disrespect or verbal attacks against other users, misleading links, intentionally wrong answers, and other forms of disruptive behaviour not otherwise specified are unwelcome. Disruptive behaviour includes (but is not restricted to) the operation of unauthorized bots in the channel, public logging of the channel, and scripts such as those that publicly announce what track your MP3 player is playing or your away status.

If you have more than 5 lines of text to paste, use pastebin for your data and then paste the URL into channel.

Dealing With the Channel Staff

From time to time, you may be asked to take conversations elsewhere, treat others reasonably, steer a conversation in a particular direction, or a variety of other things in order to preserve the ambiance and usefulness of the channel. If you’re the target of such a request, please be as reasonable as you can and if you wish to take issue with it, do so in a private message with the channel staffer in question, rather than making noise in channel.

Discipline

Repeated breaking of the rules will cause channel staffers to mute (+q), ban (+b), kick, or otherwise remove you from the channel. This will particularly apply if you’re seen to be willfully ignoring the rules after we’ve drawn your attention to them.

Many forms of disruptive behaviour, such as flooding or trolling, may result in discipline without a warning. We try and avoid the use of force wherever possible and we’d appreciate it if you’d help us in pursuing this goal!

If you’re a bystander while a staffer is forced to use his or her powers for channel management, we’d appreciate your understanding and consideration in awaiting the end of the incident, and your assistance in keeping the situation as favourable as possible by not complaining, commentating, or gloating. This serves to make antisocial behaviour such as flooding less attractive (the smaller the reaction, the less the return on the malfeasance), and so benefits you as well as us!

Thanks for your cooperation and help in making the #kali-linux a more enjoyable, friendlier, and more productive experience for everyone involved.

Kali Linux Community Forums

The official community forums for the Kali Linux project are located at forums.kali.org.

It’s our goal that everyone feel welcome in the Kali Linux community, and to ensure that everyone understands the expectations, we have outlined some simple rules below. Please take a few moments to review them before joining the forums.

Forum Rules

By registering with our forums you agree to be bound by the following rules.

• We do not condone any illegal activity at all.
• Any advice or information offered in the forums is to be used for legal informational, professional, or educational purposes.
• New registrants’ posts will be moderated at first, causing a slight delay in the post appearing – please do not report problems with your post not appearing instantly during your first three days of membership.
• Please use sensible and descriptive titles for your posts – titles like “Please Help Me!!” or “Need Assistance” or “What Am I Doing Wrong?” etc., don’t give forum members any idea what the issue might be and are unlikely to draw either interest or assistance.
• Do not cross-post across sub-forums, please – one post in the relevant area is enough!
• Before creating a new thread, please search the forums for similar or related previous postings. If you do create a new thread asking a question that has already been asked, don’t be surprised if your thread gets deleted without notice.
• Do not post about breaking into networks that do not belong to you and for which you have no permissions. Do not post about illegal activities.
• Religious, political, or pornographic references will not be tolerated. Stay on topic.
• Posts about your success in “hacking” into your neighbours WiFi or queries about how to break into a network, etc., are not welcome and will vanish (quite possibly along with your user ID).
• Spam messages they will be summarily removed, and you will be summarily banned if you posted them.
• Members signatures may not contain URLs or web links, in any form.
• We will not tolerate abusive, sexist, racist, or any other derogatory remarks, nor members acting like self-appointed moderators. The forum staff are responsible for moderation, and they’re here to help you. Please use their services.
• If ANY member has an issue with the content of ANY post within the forums, use the “REPORT THIS POST” button – This is the red triangle icon when using the default forum theme (or the asterisk icon when using the Blackfire Razor forum theme) found in the top right corner of each post.
• Breaking the forum rules may incur infractions ranging from loss of posting privileges to a temporary or permanent ban, at the sole discretion of the forum staff.
• These rules are subject to alteration and/or addition. You are responsible for staying aware of any changes.

Submitting Bugs for Kali Linux

Introduction

This article is a guide for putting together a bug report so that it gets addressed as quickly as possible.

First, Kali Linux is a labor of love, born out of a desire to give back to the community, a community that we’re a part of. In our development roles, it’s our goal to continually improve and evolve the project, making things better for the entire community of Kali Linux users. The developers who provide support to you are volunteers doing so out of altruism. Kali Linux is their gift to you. Please keep this in mind when making your comments.

Second, the goal of a successful bug report is to enable the Kali Linux developers to reproduce the issue and see the failure, if any. If the Kali development team can reproduce the reported failure, they can proceed to gather extra information until the root cause is determined. If the failure can’t be reproduced, the development team will request additional information until they can reproduce the results reported by the submitter.

Please note, submissions are best read by our team in English.

Help us help you! To give us the best start in getting your issue resolved:

• Supply all the information you can. Try to stick to what’s relevant, but if you’re uncertain, too much is better than too little.
• Keep your bug report objective and try to stick to the facts at hand.
  • Be very clear about what is a fact — document these whenever possible, via logs, scrollback captures, etc. — and what is a hypothesis on your part.
  • Do not quote Wikipedia and other non-primary resources as “facts” in your submission. What’s happening on your system is what’s at issue, not what Wikipedia claims
• Do not stack multiple issues into a single report; submit additional reports as needed. One person should submit one report, for one bug, on one particular hardware combination. Trying to stack multiple variations into a single report makes any specific issue in there very difficult to tease out. What seem like similar bugs to you may in fact turn out to be unrelated.
• If one of the developers asks for additional information, please do your best to understand what’s being asked for and provide it in a reasonable time. If you’re not sure you understand what you’re being asked for, ask for clarification, we’ll do our best to provide more guidance. Do not post comments that are unhelpful such as “Me too!” or “+1”.
• Do not complain about how long it takes to fix a bug. Remember: the developers are volunteers with day jobs, which are not fixing your bugs for you.

How to Report a Bug

The Kali Linux Bug Tracker can be found at https://bugs.kali.org. This section will guide you through signing up for a new account, creating a system profile, and  creating a detailed bug report for submission to the Bug Tracker.

Signing Up For a Bug Tracker Account

You’ll have to create an account before the Bug Tracker will allow you to submit reports or comment on existing ones.

On the bug tracker website, click Signup for new account.

Provide a username, e-mail address, and respond to the CAPTCHA challenge. Click the Signupbutton to proceed.

If successful, the next page will notify you that the account registration has been processed and the bug tracker system will send a confirmation email to the address you provided. You will need to visit the link in the email in order to activate your account.

Once your account has been activated, click Proceed to continue to the Bug Tracker login page.

Creating a Profile in the Kali Linux Bug Tracker

Although not required, we recommend you create a unique profile as part of your Bug Tracker account. Profiles are shortcuts that predefine values for your CPU platform, operating system and version, as well as allowing you to provide some additional information, all of which is automatically submitted as part of your bug report. You can create a custom profile for each Kali system you’re using or select from the default profiles provided.

To create or edit a custom profile, select My Account from the main page and then select Profiles. Add the specific information and description for your system and click the Add Profile button when done.

Once the profile has been added, it will appear in the Select Profile drop-down list when you report a new issue. Create as many different profiles as you need, just be sure to select the appropriate one when submitting your bug report, or a lot of confusion may result.

Be Sure You Are Not Duplicating a Previous Report

Before starting your report, search the site for keywords related to your issue. If there is already an existing bug not related to hardware, please do not duplicate the request or add notes that provide no new information or are otherwise unnecessary (e.g. “Me Too” or “+1”). If the bug has already been reported, you can view the status of any progress toward resolving the issue by clicking the ID link.

However, if you believe the issue to be hardware related, please submit a new report with your specific information, even if it appears similar. There is a strong chance that your hardware does not exactly match that of another reporter. Do not assume that just because you have the same desktop or laptop model that your issue is not unique.

Creating the Report

To begin your report, log into your account and click the Report Issue link on the landing page. You will need to provide as much information as you possibly can. If unsure, review the pointers at the beginning of this document.

The following fields are mandatory within the report:

• Category
• Summary
• Description

Even though the other fields are not mandatory, we recommend you try to include as much information as possible within each option while paying special attention to the following fields:

• Reproducibility — How reproducible is this bug? Always? Only sometimes? Only under specific circumstances?
• Select Profile — We need to know what you’re running, and what you’re running it on.
• Steps to Reproduce — Be very clear here, and provide as much concrete detail as you can.
• Additional Information
• Upload File (error logs, screenshot)

Decide the Proper Category

There are currently four (4) categories available in the Kali bug tracker. Before you begin your request, ensure it is properly designated for one of the following:

• General Bug
• Kali Package Bug
• New Tool Requests
• Tool Upgrade

Do not request support or ask questions within the bug tracker. Kali Linux offers several options for support including http://docs.kali.org , https://forums.kali.org, and our IRC chat room (#kali-linux on freenode)

Providing a Descriptive Summary

The summary field is essentially the ‘title’ of the bug report and it will be the first thing Kali developers and other visitors see. Provide a short, yet descriptive, summary that describes the issue or request.

A good summary: Chromium Package installed from repo will not run as root user

A bad summary: Chromium doesn’t work

The summary does not need to include everything, but it should convey your reason for submitting the report.

Using dpkg to Find the Package and Version for the Report

You can find which package is installed using a combination of dpkg flags. It is important to include relevant information from the output of these commands in your report. The output can also be placed in a text file and uploaded. (Discussed later within this document.)

• dpkg –search
• dpkg –list
• dpkg –status

Sample Output

root@kali:~# which chromium
/usr/bin/chromium
root@kali:~# type chromium
chromium is /usr/bin/chromium
root@kali:~# dpkg –search /usr/bin/chromium
chromium: /usr/bin/chromium
root@kali:~# dpkg –list chromium
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name           Version      Architecture Description
+++-==============-============-============-=================================
ii  chromium       55.0.2883.75-3 amd64        Google open source chromium web
root@kali:~# dpkg –status chromium
Package: chromium
Status: install ok installed
Priority: optional
Section: web
Installed-Size: 160895
Maintainer: Debian Chromium Maintainers <pkg-chromium-maint@lists.alioth.debian.org>
Architecture: amd64
Source: chromium-browser
Version: 55.0.2883.75-3
…Output Truncated…

Building the Description Scenario

This is your opportunity to to help us out and provide a well thought-out description of the problem you’re experiencing. Please provide as many details and facts as possible.

Please ensure you include the following where applicable:

• Exact and complete text of any error messages (screen output or log files)
• Exactly what you typed or what actions you took to produce the issue
• A suggested fix, workaround, or patch if you are able to produce one
• The version of the package having the problem, and any information relating to dependent packages
• The kernel version, shared C library, and any other details that seem appropriate
• The output of the command uname –a
• The output of the command dpkg -s libc6 | grep ^Version
• If applicable, software version — ( i.e. python –V, etc.)
• Details of your hardware
• If you are reporting an issue with a device driver, please provide full details on all hardware in your system — for a complete report on your system install lshw from the repos.
• Add any other details that seems relevant
• Do not worry about the report being “too long” — as long as the information is relevant, include it.

Here’s an example of a good bug report, providing information that the development team can immediately use to reproduce and try to understand the bug:

---

 

Package: Chromium

Architecture: amd64

Maintainer: Debian Chromium Maintainers

Source: chromium-browser

Version: 55.0.2883.75-3

I installed the chromium web browser from the Kali Linux repos, using the command ‘apt install chromium’. I launched the program from the Kali menu by selecting Applications/Internet/Chromium Web Browser. Chromium did not launch as expected, instead it provided an error pop-up window.

The error message stated, “Chromium cannot be run as root. Please start Chromium as a normal user. To run as root, you must specify an alternate –user-data-dir for storage of profile information”.

I clicked the Close button to close the pop up window.

uname –a output: Linux kali 4.7.0-kali1-amd64 #1 SMP Debian 4.7.6-1kali1 (2016-10-17) x86_64 GNU/Linux

C Library Version: 2.24-8

---

The Importance of Reproducibility

The Kali Linux bug tracker allows you to provide the frequency of the issue being reported. If you are submitting a request for a new tool or an upgrade to an existing tool, simply select N/Afrom the drop down options. If submitting a bug, please provide the appropriate response.

Continuing the example above, by design, Chromium will not launch as root, so you would select ‘always’ from the drop-down menu.

It is extremely important you provide an accurate response. If the Kali developers attempt to reproduce the issue, they need to know the frequency. If the issue happens occasionally but you have marked ‘always’, the issue may be closed prematurely as the developer doing the testing may not experience the issue.

Selecting the Proper Profile

As discussed above, using a custom-defined profile is best for each issue reported. If custom profiles are not created, select the appropriate “standard” profile from the drop-down menu. At the time of this writing, the following options are available.

• armel Kali 1.0
• armhf Kali 1.0
• x64 Kali 1.0
• x86 Kali 1.0

Providing Steps to Reproduce the Issue

Although this may seem redundant when compared with the description section, this section should only include the steps taken to reproduce the issue. Some steps may seem unnecessary, but it is important to ensure you document the process as well as you can. The missing step may be the one that’s key to reproducing the issue.

Here’s an example of a good set of steps for reproducing our example Chromium bug.

---

1. 1. Opened a terminal window by selecting Applications/Accessories/Terminal
   2. Typed ‘apt install chromium’ in the terminal and hit enter to run the command
   3. Attempted to run Chromium web browser by selecting Applications/Internet/Chromium Web Browser

---

 

Providing Additional Information

In this section, you can provide any additional information you believe is relevant to the issue. If you have a fix or workaround for the issue, please provide it in this section. Again, it is important to stick to the facts and document the steps clearly so the developers can reproduce the issue.

An example of some useful “Additional Information”:

---

There is a simple fix that is well documented on several forums. I tried it and it fixed the issue for me.

• Using a text editor open /etc/chromium/default
• Add –user-data-dir flag
• i.e. CHROMIUM_FLAGS=”–user-data-dir”

Can this be patched within the repo version of Chromium so adding this flag is not required for future releases?

---

Uploading Relevant Files

Sometimes it is important to provide information to the development team that can’t easily be typed in as text. This section of the report allows you to add screenshots and log files. Be mindful of the size limitation in place.

You can add a file by clicking the ‘Choose File’ button. This will open the file manager for your system and allow you to select the file you want to attach to your report. Once you have selected the file, click the ‘Open’ button to return to your report and click the ‘Upload File’ button.

Submitting the Report

At this point, you are ready to submit the report. All that is left to do is click the ‘Submit Report’ button. Your report will be submitted and assigned a tracking ID. The report will show up on your ‘My View’ page under ‘Reported by Me’. This will allow you to track the issue to resolution.

Summary

Bug reports help the Kali Linux development team see the failure with their own eyes. Since they cannot be with you to experience the problem you’re having, you must provide instructions detailed enough that they can make their own systems fail themselves.

Describe everything in detail, stating the steps taken, what you saw, what you did, as well as the expected outcome.

Attempt to find an issue or fix through research, if at all possible — remember, open source development is a participatory process! If you are able to provide a solution to fix the issue for your system, provide the developers with the same level of detail as you did when reporting the bug. It is important that the developers know exactly what you did, so they can successfully repeat the process. This should not stop you from filing a full explanation of the symptom that caused the unexpected behavior.

Write accurately, be clear, precise, and concise to ensure the developers cannot misinterpret what you are trying to convey.

Be prepared to provide additional information; the developers will not ask if they don’t need the information.

Please be patient with your request, the developers want to fix your issue as much as you do. We love what we do and are proud to continue making Kali Linux the most advanced penetration testing distribution ever, and grateful for the assistance we get from you, our community of users, in doing so.

Preparing a Kali Linux ARM chroot

Although you can download pre-rolled Kali ARM images from our Download area, there may be applications which will require building your own custom bootstrapped Kali rootfs for ARM.

The following procedure shows an example of building a fairly generic Kali armhf rootfs. If you wish to build for armel, use that value rather than “armhf” when you export the architecture environment variable.

Some Notes on This Procedure

The intention in this article is more to provide a high-level overview of how the build scripts work than an actual manual procedure (although it’s completely possible to walk through this example at the command line). The style mimics that used in the build scripts used to create the pre-rolled images. Specifically, you’ll see a construct in several places that looks like:

cat << EOF > kali-$architecture/etc/apt/sources.list
deb http://http.kali.org/kali kali-rolling main non-free contrib
#deb-src http://http.kali.org/kali kali-rolling main non-free contrib
EOF

This simply amounts to creating a new file, ~/arm-stuff/rootfs/kali-armhf/etc/apt/sources.list, with the contents

deb http://http.kali.org/kali kali-rolling main non-free contrib
#deb-src http://http.kali.org/kali kali-rolling main non-free contrib

Real-World Custom Kali Linux Builds for ARM Devices

Before we walk through our example, it’s probably good to see how a custom ARM build would actually be accomplished. Typically, to do a local build of an image for, e.g., Raspberry Pi, the process would be something like the following. As an initial one-time set-up, clone the ARM build scripts repository on GitHub and install the build prerequisites:

cd ~
git clone https://github.com/offensive-security/kali-arm-build-scripts.git
dpkg –add-architecture i386
apt update
apt -y install debootstrap qemu-user-static device-tree-compiler lzma lzop u-boot-tools libncurses5:i386 pixz

To do an ARM build, you must enable cross-compilation for your current shell session:

export ARCH=arm
mkdir -p arm-stuff/kernel/toolchains
cd arm-stuff/kernel/toolchains
git clone git://github.com/offensive-security/gcc-arm-eabi-linaro-4.6.2.git
export CROSS_COMPILE=~/arm-stuff/kernel/toolchains/gcc-arm-eabi-linaro-4.6.2/bin/arm-eabi-

Then simply invoke the build script for the specific platform. So, for a Raspberry Pi build of Kali Linux 2016.2, execute the commands:

cd ~
kali-arm-build-scripts/rpi.sh 2016.2

The ARM build scripts are all completely self-contained, aside from the initial one-time installation of the build prerequisites. The first time you run one of the ARM build scripts, it is extremely important that you inspect the output for any errors such as missing tools, etc., correct them, and then re-run the script until you get a clean build. Only at that point can you go ahead to make any customizations you want to the basic build script to create the specific “recipe” you’re after.

It’s possible to speed up your builds by caching the packages you download using apt-cacher-ng, as described in the previous article. Note that this can break some of the standard build scripts unless you uncomment certain lines before building — they’re noted in the scripts themselves. If you’re using apt-cacher-ng, make sure you check your scripts for any necessary changes.

For reliable and predictable results, build your Kali Linix ARM chroot from within a pre-existing and up-to-date Kali Linux environment. This guide assumes that you have already set up your ARM cross-compilation environment.

An Annotated Example of a Generic ARM Build of Kali Linux

The build described here is both minimal and generic. A small number of basic packages are included, and the fuller configuration needed for a real-world platform is omitted for the sake of clarity. Use this example as a reference for understanding what’s going on in the official ARM build scripts and as a high-level guide for writing your own build scripts. It can be successfully followed as a stand-alone tutorial from the command line, but the image produced is not likely to run on any particular device. Use the pre-rolled build scripts, either as-is or with your own customizations, to produce working images for concrete hardware.

Install Required Tools and Dependencies

This is a general set-up task, and should only ever need to be done once.

apt install debootstrap qemu-user-static

Enable Cross-Compilation

In order to enable the Linaro cross-compilation, you will need to set these environment variable at the beginning of every session.

export ARCH=arm
export CROSS_COMPILE=~/arm-stuff/kernel/toolchains/gcc-arm-eabi-linaro-4.6.2/bin/arm-eabi-

Define Architecture and Custom Packages

This is where you define some environment variables for your required ARM architecture (armel vs armhf) and list the packages to be installed in your image. These will be used throughout this article, so make sure to modify them to your needs.

export packages=“xfce4 kali-menu wpasupplicant kali-defaults initramfs-tools u-boot-tools nmap openssh-server”
export architecture=“armhf”

Build the Kali rootfs

Set Up the Base rootfs

As our starting point, we’ll create a standard directory structure and use debootstrap to install a base ARM rootfs from the Kali Linux repositories. We then copy over qemu-arm-static, an ARM emulator, from our host machine into the rootfs in order to initiate the 2nd stage chroot.

cd ~
mkdir -p arm-stuff # should have already been created when setting up x-compilation
cd arm-stuff/
mkdir -p kernel # should have already been created when setting up x-compilation
mkdir -p rootfs
cd rootfs

debootstrap –foreign –arch $architecture kali-rolling kali-$architecture http://http.kali.org/kali
cp /usr/bin/qemu-arm-static kali-$architecture/usr/bin/

2nd Stage chroot

First, we’ll chroot into our newly-created base rootfs, use debootstrap a second time to construct our second-stage rootfs, and configure base image settings such as repositories (in /etc/apt/sources.list), host name (in /etc/hostname), default network interfaces and behavior (in /etc/network/interfaces and /etc/resolv.conf), etc. Change these to suit your requirements.

cd ~/arm-stuff/rootfs
LANG=C chroot kali-$architecture /debootstrap/debootstrap –second-stage

cat << EOF > kali-$architecture/etc/apt/sources.list
deb http://http.kali.org/kali kali-rolling main non-free contrib
# deb-src http://http.kali.org/kali kali-rolling main non-free contrib
EOF

echo “kali” > kali-$architecture/etc/hostname

cat << EOF > kali-$architecture/etc/network/interfaces
auto lo
iface lo inet loopback
auto eth0
iface eth0 inet dhcp
EOF

cat << EOF > kali-$architecture/etc/resolv.conf
nameserver 8.8.8.8
EOF

Now, we’re ready to assemble our third-stage chroot.

3rd Stage chroot

This is where your specific customizations come in. Your $packages list is installed, as are keymaps, a default root password of “toor” is set, and other configuration changes and fixes are applied.

export MALLOC_CHECK_=0 # workaround for LP: #520465
export LC_ALL=C
export DEBIAN_FRONTEND=noninteractive

mount -t proc proc kali-$architecture/proc
mount -o bind /dev/ kali-$architecture/dev/
mount -o bind /dev/pts kali-$architecture/dev/pts

cat << EOF > kali-$architecture/debconf.set
console-common console-data/keymap/policy select Select keymap from full list
console-common console-data/keymap/full select en-latin1-nodeadkeys
EOF

Here, we’ll create the script to do the third-stage chroot

cat << EOF > kali-$architecture/third-stage
#!/bin/bash
dpkg-divert –add –local –divert /usr/sbin/invoke-rc.d.chroot –rename /usr/sbin/invoke-rc.d
cp /bin/true /usr/sbin/invoke-rc.d

apt update
apt install locales-all
#locale-gen en_US.UTF-8

debconf-set-selections /debconf.set
rm -f /debconf.set
apt update
apt -y install git-core binutils ca-certificates initramfs-tools u-boot-tools
apt -y install locales console-common less nano git
echo “root:toor” | chpasswd
sed -i -e ‘s/KERNEL\!=”eth\*|/KERNEL\!=”/’ /lib/udev/rules.d/75-persistent-net-generator.rules
rm -f /etc/udev/rules.d/70-persistent-net.rules
apt-get –yes –force-yes install $packages

rm -f /usr/sbin/invoke-rc.d
dpkg-divert –remove –rename /usr/sbin/invoke-rc.d

rm -f /third-stage
EOF

Now, we’ll run it from within our second-stage chroot.

chmod +x kali-$architecture/third-stage
LANG=C chroot kali-$architecture /third-stage

Manual Configuration Within the chroot

If you need to make any further modifications in your rootfs environment, you can do so by manually chrooting into it with the following command and making any needed changes.

LANG=C chroot kali-$architecture

Once you’ve completed your modifications, leave the chroot’ed rootfs with the command

exit

Cleanup

Lastly, we create and run a cleanup script in our chroot to free up space used by cached files and run any other cleanup jobs we may require, and unmount the directories we were using in our rootfs.

cat << EOF > kali-$architecture/cleanup
#!/bin/bash
rm -rf /root/.bash_history
apt update
apt clean
rm -f cleanup
EOF

chmod +x kali-$architecture/cleanup
LANG=C chroot kali-$architecture /cleanup

umount kali-$architecture/proc
umount kali-$architecture/dev/pts
umount kali-$architecture/dev/

cd ..

Congratulations! Your custom Kali ARM rootfs is located in the ~/arm-stuff/rootfs/kali-$architecture directory. You can now tar up this directory or convert it to an image file for further work.

ARM Cross-Compilation

The following guide will demonstrate how to set up an ARM cross-compilation environment in Kali Linux. This guide is the starting point for many of our contributed “Custom ARM Images” articles.

Setting Up Your Development Box

Compiling kernels and generating images usually comes at the cost of disk space. Make sure you have at least 50 GB of disk space available on your Kali development machine as well as ample RAM and CPU juice.

Install Dependencies

Start off by installing the required dependencies for ARM cross-compilation.

apt install git-core gnupg flex bison gperf libesd0-dev build-essential \
zip curl libncurses5-dev zlib1g-dev gcc-multilib g++-multilib

If you are running a 64 bit Kali Linux system, add i386 architecture support to your development environment as follows.

dpkg –add-architecture i386
apt update
apt install ia32-libs

Download Linaro Toolchain

Download the Linaro cross-compiler from our Git repository.

cd ~
mkdir -p arm-stuff/kernel/toolchains
cd arm-stuff/kernel/toolchains
git clone git://github.com/offensive-security/gcc-arm-eabi-linaro-4.6.2.git

Set Environment Variables

To use the Linaro cross-compiler, you will need to set the following environment variables in your session.

export ARCH=arm
export CROSS_COMPILE=~/arm-stuff/kernel/toolchains/gcc-arm-eabi-linaro-4.6.2/bin/arm-eabi-

Now your ARM cross-compilation environment is complete and you can proceed with building your own ARM kernels as described in the article on preparing a Kali Linux ARM chroot.

Recompiling the Kali Linux Kernel

The customizability of Kali Linux extends all the way down into the Linux kernel.

Depending on your requirements, you might want to add drivers, patches, or kernel features that are not included in the stock Kali Linux kernel. The following guide will describe how the Kali Linux kernel can be quickly modified and recompiled for your needs. Note that global wireless injection patches are already present by default in the Kali Linux kernel.

Install Build Dependencies
Start by installing all the build dependencies for recompiling the kernel.

apt install build-essential libncurses5-dev fakeroot unxz
Download the Kali Linux Kernel Source Code
The remainder of this section focuses on the 4.9 version of the Linux kernel, but the examples can, of course, be adapted to the particular version of the kernel that you want. We assume that the linux-source-4.9 binary package has been installed. Note that we install a binary package containing the upstream sources, we do not retrieve the Kali source package named linux.

apt install linux-source-4.9
Reading package lists… Done
Building dependency tree
Reading state information… Done
The following additional packages will be installed:
bc libreadline7
Suggested packages:
libncurses-dev | ncurses-dev libqt4-dev
The following NEW packages will be installed:
bc libreadline7 linux-source-4.9
0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded.
Need to get 95.4 MB of archives.
After this operation, 95.8 MB of additional disk space will be used.
Do you want to continue? [Y/n] y
[…]
ls /usr/src
linux-config-4.9 linux-patch-4.9-rt.patch.xz linux-source-4.9.tar.xz
Notice that the package contains /usr/src/linux-source-4.9.tar.xz, a compressed archive of the kernel sources. You must extract these files in a new directory (not directly under /usr/src/, since there is no need for special permissions to compile a Linux kernel). Instead, ~/kernel/ is more appropriate.

mkdir ~/kernel; cd ~/kernel
tar -xaf /usr/src/linux-source-4.9.tar.xz
Configure Your Kernel
When recompiling a more recent version of the kernel (possibly with an additional patch), the configuration will most likely be kept as close as possible to that proposed by Kali. In this case, and rather than reconfiguring everything from scratch, it is sufficient to copy the /boot/config-version file (the version is that of the kernel currently used, which can be found with the uname -r command) into a .config file in the directory containing the kernel sources.

cp /boot/config-4.9.0-kali1-amd64 ~/kernel/linux-source-4.9/.config
If you need to make changes or if you decide to reconfigure everything from scratch, you must take the time to configure your kernel. This can be done by calling the make menuconfig command.

make menuconfig
The details of using menuconfig to set up a kernel build are beyond the scope of this guide. There is a detailed tutorial on configuring a kernel build on Linux.org.

Build the Kernel
Once the kernel configuration is ready, a simple make deb-pkg will generate up to 5 Debian packages: linux-image-version that contains the kernel image and the associated modules, linux-headers-version, which contains the header files required to build external modules, linux-firmware-image-version, which contains the firmware files needed by some drivers (this package might be missing when you build from the kernel sources provided by Debian or Kali), linux-image-version-dbg, which contains the debugging symbols for the kernel image and its modules, and linux-libc-dev, which contains headers relevant to some user-space libraries like GNU glibc. The Linux kernel image is a big build, expect it to take a while to complete.

make clean
make deb-pkg LOCALVERSION=-custom KDEB_PKGVERSION=$(make kernelversion)-1
[…]
ls ../*.deb
../linux-headers-4.9.0-kali1-custom_4.9.2-1_amd64.deb
../linux-image-4.9.0-kali1-custom_4.9.2-1_amd64.deb
../linux-image-4.9.0-kali1-custom-dbg_4.9.2-1_amd64.deb
../linux-libc-dev_4.9.2-1_amd64.deb
Install the Modified Kernel
When the build has successfully completed, you can go ahead and install the new custom kernel and reboot your system. Please note that the specific kernel version numbers will vary — in our example, done on a Kali 2016.2 system, it was 4.9.2. Depending on the current kernel version you’re building, you will need to adjust your commands accordingly.

dpkg -i ../linux-image-4.9.0-kali1-custom_4.9.2-1_amd64.deb
reboot
Once your system has rebooted, your new kernel should be running. If things go wrong and your kernel fails to boot successfully, you can still use the GrUB menu to boot from the original stock Kali kernel and fix your issues.

Live Build a Custom Kali ISO

An Introduction to Building Your Own Kali ISO

Building a customized Kali ISO is easy, fun, and rewarding. You can configure virtually any aspect of your Kali ISO build using the Debian live-build scripts. These scripts allow developers to easily build live system images by providing a framework that uses a configuration set to automate and customize all aspects of building the image. The Kali Linux development team has adopted these scripts and they’re used to produce the official Kali ISO releases.

Where Should You Build Your ISO?

Ideally, you should build your custom Kali ISO from within a pre-existing Kali environment.

Getting Ready — Setting up the live-build system

We first need to prepare the Kali ISO build environment by installing and setting up live-build and its requirements with the following commands:

apt install curl git live-build cdebootstrap
git clone git://git.kali.org/live-build-config.git

Now you can simply build an updated Kali ISO by entering the “live-build-config” directory and running our build.sh wrapper script, as follows:

cd live-build-config
./build.sh –distribution kali-rolling –verbose

The “build.sh” script will take a while to complete, as it downloads all of the required packages needed to create your ISO. Good time for a coffee.

Configuring the Kali ISO Build (Optional)

If you want to customize your Kali Linux ISO, this section will explain some of the details. Through the kali-config directory, the Kali Linux live build supports a wide range of customization options, which are well-documented on the Debian live-build man page. However, for the impatient, here are some of the highlights.

Building Kali with Different Desktop Environments

Since Kali 2.0, we now support built in configurations for various desktop environments, including KDE, Gnome, E17, I3WM, LXDE, MATE and XFCE. To build any of these, you would use syntax similar to the following:

# These are the different Desktop Environment build options:
#./build.sh –distribution kali-rolling –variant {gnome,kde,xfce,mate,e17,lxde,i3wm} –verbose

# To build a KDE ISO:
./build.sh –distribution kali-rolling –variant kde –verbose
# To build a MATE ISO:
./build.sh –distribution kali-rolling –variant mate –verbose

#…and so on.

Controlling the Packages Included in Your Build

The list of packages included in your build will be present in the the respective kali-$variant directory. For example, if you’re building a default Gnome ISO, you would use the following package lists file – kali-config/variant-gnome/package-lists/kali.list.chroot. By default, this list includes the “kali-linux-full” metapackage, as well as some others. These can be commented out and replaced with a manual list of packages to include in the ISO for greater granularity.

Build Hooks, Binary, and Chroot

Live-build hooks allows us to hook scripts in various stages of the Kali ISO live build. For more detailed information about hooks and how to use them, refer to the live build manual. As an example, we recommend you check out the existing hooks in kali-config/common/hooks/.

Overlaying files in your build

You have the option to include additional files or scripts in your build by overlaying them on the existing filesystem, inside the includes.{chroot,binary,installer} directories, respectively. For example, if we wanted to include our own custom script into the /root/ directory of the ISO (this would correspond to the “chroot” stage), then we would drop this script file in the kali-config/common/includes.chroot/ directory before building the ISO.

Building a Kali Linux ISO for Older i386 Architectures

The Kali Linux i386 ISO has PAE enabled. If you require a default kernel for older hardware with PAE disabled, you will need to rebuild a Kali Linux ISO. The rebuilding process is much the same as described above, except that the 686-pae parameter that needs to be changed to 686in auto/config as follows. First, install the prerequisites.

apt install curl git live-build cdebootstrap debootstrap
git clone git://git.kali.org/live-build-config.git

Next, make the change in auto/config for the appropriate architecture:

cd live-build-config
sed -i ‘s/686-pae/686/g’ auto/config

Finally, run your build.

./build.sh –distribution kali-rolling –arch i386 –verbose

Rebuilding a Source Package

Kali Linux is easy to customize at a per-package level, and it’s equally simple to make modifications to individual packages and rebuild them from their source code for inclusion in your custom ISO or on your desktop install.

Accomplishing this is a simple three-step process:

• use apt to pull down the package sources
• modify them as needed
• rebuild the package using the Debian tools.

In this example, we will rebuild the libfreefare package in order to add some extra hardcoded Mifare access keys into the mifare-format tool.

Downloading the Package Source

# Get the source package
apt update
apt-get source libfreefare
cd libfreefare-0.4.0/

Edit the Package Source Code

Make the changes needed to the source code of the package. In our case, we modify an example file, mifare-classic-format.c.

nano examples/mifare-classic-format.c

Check for Build Dependencies

Check for any build dependencies the package may have. These need to be installed before you can build the package.

dpkg-checkbuilddeps

The output should be similar to the following, depending on what packages you already have installed. If dpkg-checkbuilddeps returns no output, that means you can proceed with the build, all of the dependencies are already satisfied.

dpkg-checkbuilddeps: Unmet build dependencies: dh-autoreconf libnfc-dev libssl-dev

Install Build Dependencies

Install any build dependencies if needed, as shown in the output of dpkg-checkbuilddeps:

apt install dh-autoreconf libnfc-dev libssl-dev

Build the Modified Package

With all of the dependencies installed, the dpkg-buildpackage command is all it takes to build your new version.

dpkg-buildpackage

Install the New Package

If the build completes without errors, you’ll be able to install your newly-created package with dpkg.

dpkg -i ../libfreefare*.deb